Repository navigation
docs: A README demo of agents working in several projects at once #10
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Changes from all commits
2eff942
7a1320b
51d4d53
0bac6d9
3dc036a
957981b
987df2c
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Nothing references this MP4, and the description says it's only there in case we want it some day. That puts 2.4 MB into git history for good. Leave it out until something embeds it (encode.sh can still write it locally).
Contributor
Author
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Thanks, but I'd rather keep it. We'll likely use the MP4 elsewhere soon (it's the same cut at full size), and recording it again later would mean another full run with real agents. There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Fair, that's a size vs. re-record cost call. Leaving it to the maintainers whether 2.4MB of unreferenced binary in git history for good is worth avoiding another full run. |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,103 @@ | ||
| // The demo daemon's API, for seeding and for waiting on agents while recording. | ||
| import { readFileSync } from 'node:fs'; | ||
| import { dirname, join } from 'node:path'; | ||
| import { fileURLToPath } from 'node:url'; | ||
|
|
||
| const here = dirname(fileURLToPath(import.meta.url)); | ||
| export const layout = JSON.parse(readFileSync(join(here, 'layout.json'), 'utf8')); | ||
| const TOKEN = process.env.HOMESHELL_API_TOKEN ?? 'demo-token'; | ||
| let base = process.env.DEMO_URL ?? 'http://127.0.0.1:8431'; | ||
|
|
||
| export const setBase = (url) => { | ||
| base = url; | ||
| }; | ||
| export const pause = (ms) => new Promise((r) => setTimeout(r, ms)); | ||
|
|
||
| export async function api(method, path, body) { | ||
| const res = await fetch(`${base}/api${path}`, { | ||
| method, | ||
| headers: { Authorization: `Bearer ${TOKEN}`, 'Content-Type': 'application/json' }, | ||
| body: body === undefined ? undefined : JSON.stringify(body), | ||
| }); | ||
| if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${await res.text()}`); | ||
| return res.status === 204 ? null : res.json().catch(() => null); | ||
| } | ||
|
|
||
| export const projects = async () => (await api('GET', '/projects')).projects; | ||
| export const project = async (name) => (await projects()).find((p) => p.name === name); | ||
| export const wsPath = (p, ws) => `/projects/${p.id}/workstreams/${ws.id}`; | ||
|
|
||
| export async function workstream(projectName, wsName) { | ||
| const p = await project(projectName); | ||
| const ws = p?.workstreams.find((w) => w.name === wsName); | ||
| if (!ws) throw new Error(`no workstream ${projectName}/${wsName}`); | ||
| return { p, ws }; | ||
| } | ||
|
|
||
| /** Every session with its project and workstream names. */ | ||
| export async function allSessions() { | ||
| const out = []; | ||
| for (const p of await projects()) | ||
| for (const w of p.workstreams) for (const s of w.sessions ?? []) out.push({ ...s, project: p.name, ws: w.name }); | ||
| return out; | ||
| } | ||
|
|
||
| /** Polls until `poll()` returns something truthy; throws `what` after `timeoutMs`. */ | ||
| export async function until(what, poll, timeoutMs = 120_000, everyMs = 500) { | ||
| const end = Date.now() + timeoutMs; | ||
| for (;;) { | ||
| const v = await poll(); | ||
| if (v) return v; | ||
| if (Date.now() > end) throw new Error(`timed out after ${timeoutMs / 1000}s: ${what}`); | ||
| await pause(everyMs); | ||
| } | ||
| } | ||
|
|
||
| /** The session of `projectName/wsName` matching `pick` (default: the newest), once it is in `states`. */ | ||
| export async function waitForSession(projectName, wsName, states, { timeoutMs = 300_000, pick } = {}) { | ||
| let last; | ||
| try { | ||
| return await until( | ||
| `${projectName}/${wsName} session in ${states}`, | ||
| async () => { | ||
| const list = (await allSessions()).filter((s) => s.project === projectName && s.ws === wsName && !s.placeholder); | ||
| last = pick ? list.find(pick) : list.at(-1); | ||
| return last && states.includes(last.state) ? last : null; | ||
| }, | ||
| timeoutMs, | ||
| ); | ||
| } catch (err) { | ||
| err.message += `\nlast state: ${last?.state}\nlast preview:\n${last?.preview ?? '(none)'}`; | ||
| throw err; | ||
| } | ||
| } | ||
|
|
||
| /** Creates a worktree workstream named `name` and waits until it exists. */ | ||
| export async function addWorktree(projectName, name) { | ||
| const p = await project(projectName); | ||
| if (!p.workstreams.some((w) => w.name === name)) | ||
| await api('POST', `/projects/${p.id}/workstreams`, { providerId: 'core', name, config: { strategy: 'worktree' } }); | ||
| return until(`worktree ${projectName}/${name}`, async () => { | ||
| const ws = (await project(projectName)).workstreams.find((w) => w.name === name); | ||
| if (ws?.status?.kind === 'error') throw new Error(`creating ${name}: ${ws.status.message}`); | ||
| return ws && !ws.placeholder && ws.state !== 'creating' && !ws.id.startsWith('creating-') ? ws : null; | ||
| }); | ||
| } | ||
|
|
||
| /** Starts a Local System Claude Code session with `prompt` in `projectName/wsName`. */ | ||
| export async function startClaude(projectName, wsName, prompt, config = {}) { | ||
| const { p, ws } = await workstream(projectName, wsName); | ||
| const config_ = { model: 'claude-sonnet-5', permissionMode: 'auto', prompt, ...config }; | ||
| await api('POST', `${wsPath(p, ws)}/sessions`, { providerId: 'local', optionId: 'claude', config: config_ }); | ||
| } | ||
|
|
||
| export async function sessionAction(s, action, body) { | ||
| const { p, ws } = await workstream(s.project, s.ws); | ||
| return api('POST', `${wsPath(p, ws)}/sessions/${encodeURIComponent(s.id)}/${action}`, body); | ||
| } | ||
|
|
||
| /** Renames `s` in HomeShell, as a user does from the row's menu. */ | ||
| export async function rename(s, title) { | ||
| const { p, ws } = await workstream(s.project, s.ws); | ||
| await api('PATCH', `${wsPath(p, ws)}/sessions/${encodeURIComponent(s.id)}`, { title }); | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,179 @@ | ||
| // The virtual desktop for the README demo: a HomeShell window in Chromium, the real X pointer | ||
| // moved and clicked with xdotool (so it shows in the recording and crosses windows), and ffmpeg | ||
| // capturing the X screen. Expects DISPLAY to be the demo's Xvfb (xsession.sh). | ||
| import { execFileSync, spawn } from 'node:child_process'; | ||
| import { createRequire } from 'node:module'; | ||
| import { mkdtempSync, writeFileSync } from 'node:fs'; | ||
| import { tmpdir } from 'node:os'; | ||
| import { dirname, join } from 'node:path'; | ||
| import { fileURLToPath } from 'node:url'; | ||
|
|
||
| const here = dirname(fileURLToPath(import.meta.url)); | ||
| const require = createRequire(join(here, '../../webapp/apps/web-e2e/package.json')); | ||
| const { chromium } = require('@playwright/test'); | ||
|
|
||
| export const SCREEN = { width: 1280, height: 800 }; | ||
| export const pause = (ms) => new Promise((r) => setTimeout(r, ms)); | ||
| const xdotool = (...args) => execFileSync('xdotool', args.map(String), { encoding: 'utf8' }).trim(); | ||
|
|
||
| // -- Browser ------------------------------------------------------------------------------------ | ||
|
|
||
| /** HomeShell in a Chromium app window covering the screen, signed in with the token cookie. */ | ||
| export async function openBrowser(baseUrl, token) { | ||
| const context = await chromium.launchPersistentContext(mkdtempSync(join(tmpdir(), 'hs-demo-chromium-')), { | ||
| headless: false, | ||
| viewport: null, | ||
| colorScheme: 'dark', | ||
| ignoreDefaultArgs: ['--enable-automation'], | ||
| // X11 explicitly: with WAYLAND_DISPLAY set Chromium would open on the user's own desktop. | ||
| env: { ...process.env, WAYLAND_DISPLAY: '' }, | ||
| args: [ | ||
| `--app=${baseUrl}`, | ||
| '--ozone-platform=x11', | ||
| '--window-position=0,0', | ||
| `--window-size=${SCREEN.width},${SCREEN.height}`, | ||
| ], | ||
| }); | ||
| await context.addCookies([{ name: 'hs_api_token', value: token, url: baseUrl }]); | ||
| const page = context.pages()[0] ?? (await context.waitForEvent('page')); | ||
| await page.goto(baseUrl); | ||
| return { context, page }; | ||
| } | ||
|
|
||
| /** Where the page's viewport starts on the screen. */ | ||
| async function viewportOrigin(page) { | ||
| return page.evaluate(() => ({ | ||
| x: window.screenX + (window.outerWidth - window.innerWidth) / 2, | ||
| y: window.screenY + window.outerHeight - window.innerHeight, | ||
| })); | ||
| } | ||
|
|
||
| // -- Pointer and keyboard ---------------------------------------------------------------------- | ||
|
|
||
| let pointer = { x: SCREEN.width / 2, y: SCREEN.height / 2 }; | ||
|
|
||
| /** Glides the X pointer to a screen point, easing in and out, about 900 px per second. */ | ||
| export async function glide(x, y) { | ||
| const from = pointer; | ||
| const distance = Math.hypot(x - from.x, y - from.y); | ||
| const steps = Math.max(8, Math.round(distance / 22)); | ||
| for (let i = 1; i <= steps; i++) { | ||
| const t = i / steps; | ||
| const e = t < 0.5 ? 2 * t * t : 1 - (-2 * t + 2) ** 2 / 2; | ||
| xdotool('mousemove', Math.round(from.x + (x - from.x) * e), Math.round(from.y + (y - from.y) * e)); | ||
| await pause(16); | ||
| } | ||
| pointer = { x, y }; | ||
| } | ||
|
|
||
| /** Screen point at the centre of `locator`, or at `offset` from its top left. */ | ||
| export async function screenPoint(page, locator, offset) { | ||
| await locator.waitFor({ state: 'visible' }); | ||
| await locator.scrollIntoViewIfNeeded(); | ||
| const box = await locator.boundingBox(); | ||
| const origin = await viewportOrigin(page); | ||
| return { | ||
| x: Math.round(origin.x + box.x + (offset ? offset.x : box.width / 2)), | ||
| y: Math.round(origin.y + box.y + (offset ? offset.y : box.height / 2)), | ||
| }; | ||
| } | ||
|
|
||
| export async function pointTo(page, locator, offset) { | ||
| const p = await screenPoint(page, locator, offset); | ||
| await glide(p.x, p.y); | ||
| } | ||
|
|
||
| export async function clickAt(x, y) { | ||
| await glide(x, y); | ||
| await pause(220); | ||
| xdotool('click', 1); | ||
| await pause(120); | ||
| } | ||
|
|
||
| export async function click(page, locator, offset) { | ||
| const p = await screenPoint(page, locator, offset); | ||
| await clickAt(p.x, p.y); | ||
| } | ||
|
|
||
| /** Types into whatever has the keyboard focus, like a person (xdotool type). */ | ||
| export async function typeText(text, delayMs = 45) { | ||
| xdotool('type', '--delay', delayMs, text); | ||
| } | ||
|
|
||
| export const key = (...names) => xdotool('key', ...names); | ||
|
|
||
| // -- Windows ----------------------------------------------------------------------------------- | ||
|
|
||
| /** A window's content area on screen (xwininfo; xdotool's geometry is off by the frame). */ | ||
| function geometry(id) { | ||
| const info = execFileSync('xwininfo', ['-id', id], { encoding: 'utf8' }); | ||
| const num = (label) => Number(info.match(new RegExp(`${label}:\\s+(-?\\d+)`))[1]); | ||
| return { id, x: num('Absolute upper-left X'), y: num('Absolute upper-left Y'), width: num('Width'), height: num('Height') }; | ||
| } | ||
|
|
||
| /** Every window id currently mapped, to tell a new one apart. */ | ||
| export function windowIds() { | ||
| try { | ||
| return new Set(xdotool('search', '--onlyvisible', '--name', '.').split('\n').filter(Boolean)); | ||
| } catch { | ||
| return new Set(); // xdotool exits 1 when nothing matches | ||
| } | ||
| } | ||
|
|
||
| /** The first sizeable window mapped after `before` (windowIds()), once it has stopped moving. */ | ||
| export async function waitNewWindow(before, timeoutMs = 30_000) { | ||
| const end = Date.now() + timeoutMs; | ||
| let last; | ||
| for (;;) { | ||
| const id = [...windowIds()].find((w) => !before.has(w) && geometry(w).width > 200); | ||
| if (id) { | ||
| const geo = geometry(id); | ||
| if (last && JSON.stringify(last) === JSON.stringify(geo)) return geo; | ||
| last = geo; | ||
| } | ||
| if (Date.now() > end) throw new Error('no new window opened'); | ||
| await pause(250); | ||
| } | ||
| } | ||
|
|
||
| /** Waits until window `win` is gone. */ | ||
| export async function waitGone(win, timeoutMs = 10_000) { | ||
| const end = Date.now() + timeoutMs; | ||
| while (windowIds().has(win.id)) { | ||
| if (Date.now() > end) throw new Error(`window ${win.id} did not close`); | ||
| await pause(150); | ||
| } | ||
| } | ||
|
|
||
| /** Clicks the × of a window's title bar (metacity's frame, above the content area). */ | ||
| export async function closeWindow(win) { | ||
| await clickAt(win.x + win.width - 19, win.y - 20); | ||
| await waitGone(win); | ||
| } | ||
|
|
||
| // -- Capture ----------------------------------------------------------------------------------- | ||
|
|
||
| /** Records the X screen to `file` until the returned stop() is awaited. */ | ||
| export function startCapture(file, framerate = 25) { | ||
| const ff = spawn( | ||
| process.env.FFMPEG ?? 'ffmpeg', | ||
| ['-v', 'error', '-y', '-f', 'x11grab', '-draw_mouse', '1', '-framerate', String(framerate), | ||
| '-video_size', `${SCREEN.width}x${SCREEN.height}`, '-i', process.env.DISPLAY, | ||
| '-c:v', 'libx264', '-preset', 'ultrafast', '-crf', '0', '-pix_fmt', 'yuv444p', file], | ||
| { stdio: ['pipe', 'inherit', 'inherit'] }, | ||
| ); | ||
| const started = Date.now(); | ||
| const timeline = [{ t: 0, mode: 'normal', label: 'start' }]; | ||
| return { | ||
| /** From now on the video plays as `mode`: normal, fast (sped up) or cut (dropped). */ | ||
| mark(mode, label = '') { | ||
| timeline.push({ t: (Date.now() - started) / 1000, mode, label }); | ||
| }, | ||
| async stop(timelineFile) { | ||
| timeline.push({ t: (Date.now() - started) / 1000, mode: 'end', label: 'end' }); | ||
| ff.stdin.write('q'); | ||
| await new Promise((r) => ff.on('exit', r)); | ||
| writeFileSync(timelineFile, JSON.stringify(timeline, null, 1)); | ||
| }, | ||
| }; | ||
| } |
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,56 @@ | ||
| #!/usr/bin/env bash | ||
| # Turns a take (story.mjs) into the README GIF and an MP4 of the same cut at full size. The | ||
| # timeline marks stretches: "normal" plays at 1x, "fast" (waiting on an agent) is sped up to at | ||
| # most DEMO_FAST_SECONDS with a badge, "cut" is dropped. | ||
| # | ||
| # Usage: scripts/demo-video/encode.sh <raw.mkv> <timeline.json> <out.gif> [out.mp4] | ||
| # Env: DEMO_WIDTH (GIF width, default 1100), DEMO_FPS (GIF frame rate, default 10), | ||
| # DEMO_FAST_SECONDS (default 3), FFMPEG (default ffmpeg). | ||
| set -euo pipefail | ||
|
|
||
| raw=${1:?raw video} | ||
| timeline=${2:?timeline} | ||
| gif=${3:?output gif} | ||
| mp4=${4:-${gif%.gif}.mp4} | ||
| ffmpeg=${FFMPEG:-ffmpeg} | ||
| ffprobe=${ffmpeg%ffmpeg}ffprobe | ||
| width=${DEMO_WIDTH:-1100} | ||
| fps=${DEMO_FPS:-10} | ||
| fast=${DEMO_FAST_SECONDS:-3} | ||
| font=$(fc-match -f '%{file}' 'DejaVu Sans:bold') | ||
| work=$(mktemp -d) | ||
| trap 'rm -rf "$work"' EXIT | ||
|
|
||
| # The cut, as a filter graph ending in [cat]: every kept stretch, sped up where marked. | ||
| python3 - "$timeline" "$fast" "$font" >"$work/cut" <<'EOF' | ||
| import json, sys | ||
| marks = json.load(open(sys.argv[1])) | ||
| fast, font = float(sys.argv[2]), sys.argv[3] | ||
| segments = [] | ||
| for a, b in zip(marks, marks[1:]): | ||
| if a["mode"] != "cut" and b["t"] - a["t"] > 0.05: | ||
| segments.append((a["t"], b["t"], a["mode"])) | ||
| parts = [f"[0:v]split={len(segments)}" + "".join(f"[s{i}]" for i in range(len(segments)))] | ||
| for i, (start, end, mode) in enumerate(segments): | ||
| chain = f"[s{i}]trim=start={start:.3f}:end={end:.3f},setpts=PTS-STARTPTS" | ||
| if mode == "fast": | ||
| speed = max(4.0, (end - start) / fast) | ||
| chain += (f",setpts=PTS/{speed:.3f},drawtext=fontfile='{font}':text='>> {speed:.0f}x':fontsize=26" | ||
| ":fontcolor=white:box=1:boxcolor=0x0d9488@0.9:boxborderw=10:x=w-tw-28:y=h-th-28") | ||
| parts.append(chain + f"[v{i}]") | ||
| parts.append("".join(f"[v{i}]" for i in range(len(segments))) + f"concat=n={len(segments)}:v=1:a=0[cat]") | ||
| print(";\n".join(parts), end="") | ||
| EOF | ||
|
|
||
| { cat "$work/cut"; echo ";" | ||
| echo "[cat]fps=$fps,scale=$width:-1:flags=lanczos,split[a][b];" | ||
| echo "[a]palettegen=max_colors=192:stats_mode=diff[p];" | ||
| echo "[b][p]paletteuse=dither=bayer:bayer_scale=4:diff_mode=rectangle"; } >"$work/gif" | ||
| { cat "$work/cut"; echo ";[cat]fps=25,format=yuv420p"; } >"$work/mp4" | ||
|
|
||
| "$ffmpeg" -v error -y -i "$raw" -filter_complex_script "$work/gif" -loop 0 "$gif" | ||
| "$ffmpeg" -v error -y -i "$raw" -filter_complex_script "$work/mp4" -c:v libx264 -crf 20 -preset slow \ | ||
| -movflags +faststart "$mp4" | ||
| for f in "$gif" "$mp4"; do | ||
| echo "wrote $f ($(du -h "$f" | cut -f1), $("$ffprobe" -v error -show_entries format=duration -of csv=p=0 "$f")s)" | ||
| done |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The header in the GIF reads
daemon 0.0.0-g772bb2a, a dev build version, and that's the first thing visitors see in the README. Re-record with a release-likeVERSION(e.g.make build VERSION=...), or have the DEV.md steps set one.There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Good catch, but I'll leave it as is for now. It's a small detail in the header, and a re-take costs a full run with real agents. Next time we re-record, we can do it on a release build.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Makes sense given what a re-take costs. Leaving it to the maintainers whether a dev version string in the README's first-impression GIF is fine until the next recording.