Luxe 0.1.3: your sessions on your phone, joinable sessions, and nested AGENTS.md

- luxe remote puts the sessions on your computer in reach of your own phone or tablet over
  Tailscale: write, steer, answer prompts, send photos, browse files, diffs and GitHub, with a
  paired device and your own Tailscale login.
- luxe join lets another program on the same machine join a running session over the RPC protocol.
- An AGENTS.md in a subfolder reaches the model the first time it works there.
- Long sessions stay fast: no stall before each model call, lighter memory, cheaper drawing.
- A session is open in one Luxe at a time, web_search shares results across its phrasings, and a
  grep glob starting with ! excludes.

The CHANGELOG has the full list.
This commit is contained in:
Evan Whittaker
2026-10-20 02:40:13 -05:00
parent 99e30d6d0f
commit d2129a886f
423 changed files with 31666 additions and 1669 deletions

View File

@@ -0,0 +1,267 @@
// The app end to end in WebKit, Safari's engine: pair by pasting the invitation link, open the
// session from the list, send a message, grant the write it asks for, and watch the mock model's
// turn arrive as the TUI would show it: the rendered answer, the changed file in the dock, and its
// diff.
//
// Needs a built `luxe` (`LUXE_BIN`, or target/debug/luxe) and Playwright's WebKit
// (`npx playwright install webkit`). Run: npm run e2e
import assert from "node:assert/strict";
import { createRequire } from "node:module";
import { basename } from "node:path";
import { after, before, test } from "node:test";
import { LOGIN, startHost } from "./host.mjs";
import { WRITTEN, startMockProvider } from "./mock-provider.mjs";
const playwright = createRequire(import.meta.url)("playwright");
let model, host, browser, page;
const troubles = [];
before(async () => {
model = await startMockProvider();
host = await startHost(model.port);
browser = await playwright.webkit.launch();
const context = await browser.newContext({
...playwright.devices["iPad Pro 11 landscape"],
extraHTTPHeaders: { "Tailscale-User-Login": LOGIN },
});
page = await context.newPage();
page.on("pageerror", (error) => troubles.push(`page error: ${error.message}`));
page.on("console", (message) => message.type() === "error" && troubles.push(`console: ${message.text()}`));
});
after(async () => {
await browser?.close();
await host?.stop();
await model?.close();
});
// The break this catches: any link in the chain from invitation to diff (the unpaired app's
// pairing field, pairing, the session list, the socket, the composer, the permission card,
// rendering, the dock, the diff request) broken in Safari's engine
test("a paired iPad drives a turn and reads its diff", async () => {
await pair();
await page.locator("a.session").click();
await page.locator(".composer textarea").fill("Write the file, please.");
await page.locator(".send").click();
await page.locator(".prompt .choice.once").click();
await page.locator(".item.reply strong", { hasText: WRITTEN.path }).waitFor();
await page.locator(`button.change[data-path="${WRITTEN.path}"]`).click();
const added = page.locator(".sheet .dl-addition code");
assert.equal((await added.textContent())?.trim(), WRITTEN.content.trim());
assert.deepEqual(troubles, [], "the page ran without errors or refusals");
});
// Pairs as an app on the home screen would: the unpaired app takes the pasted link to the
// invitation page. Serve puts HTTPS in front of the bridge, so the credential is a Secure cookie,
// and WebKit drops one that arrives over this test's plain HTTP; the test carries it over itself,
// then opens the app as the page's redirect would.
async function pair() {
await page.goto(host.url);
await page.locator(".pair-link input").fill(`https://desk.example.ts.net/pair#${host.invitation}`);
await page.locator(".pair-link button").click();
const answered = page.waitForResponse("**/api/pair");
await page.locator("#pair button").click();
const cookie = (await (await answered).headerValue("set-cookie"))?.split(";")[0] ?? "";
// let the page's own redirect land and finish asking, or the visit below races it
await page.waitForURL((url) => url.pathname === "/", { waitUntil: "networkidle" });
const at = cookie.indexOf("=");
await page.context().addCookies([{ name: cookie.slice(0, at), value: cookie.slice(at + 1), url: host.url }]);
// the page's own redirect may have asked for the list before the cookie was carried over
troubles.length = 0;
await page.goto(host.url);
}
// The break this catches: the turn reaching the model without the tool's result, so the answer
// on screen came from somewhere other than the loop the app drove
test("the model saw the message and the tool's result", () => {
const turns = model.requests.filter((request) => request.tools?.length);
assert.equal(turns.length, 2, "one request to act, one with the result");
const sent = JSON.stringify(turns[0].messages);
assert.ok(sent.includes("Write the file, please."), sent);
assert.equal(turns[1].messages.at(-1).role, "tool");
});
// The break this catches: the Files tab's chain (the header's button, `list_directory` and
// `read_project_file` through the bridge, the file piece's rendering, Mention into the composer)
// broken in Safari's engine
test("the project panel lists the project, shows a file and mentions it", async () => {
await page.keyboard.press("Escape");
// The break this catches: the session's header naming its folder bare, without the branch it's on
const header = page.locator("header.bar:has(.back) .title .project-name");
await header.locator(".project-branch").waitFor();
assert.match((await header.textContent()) ?? "", new RegExp(`${basename(host.project)}.*\\S+ \\*$`));
await page.locator(".panel-button").click();
const named = page.locator(".panel .bar .project-name");
await named.waitFor();
assert.ok((await named.textContent())?.includes(basename(host.project)), "the bar names the project");
assert.ok(await named.locator(".project-mark").first().textContent(), "behind the tree's folder mark");
// the project is a git repository the turn just wrote into, so its branch shows, starred
assert.match((await named.locator(".project-branch").textContent()) ?? "", /\S+ \*$/);
// the file the turn wrote wears its change, as it does in the TUI's tree
await page.locator(`button.tree-row[data-file="${WRITTEN.path}"] .tree-name[class*="change-"]`).waitFor();
await page.locator("button.tree-row", { hasText: "README.md" }).click();
assert.equal((await page.locator(".peek .file .fl code").first().textContent())?.trim(), "# e2e");
// Escape closes the file and leaves the tree, as the TUI's Escape leaves a peek
await page.keyboard.press("Escape");
await page.locator(".peek").waitFor({ state: "detached" });
await page.locator("button.tree-row", { hasText: "README.md" }).click();
await page.locator(".peek .mention").click();
await page.waitForFunction(() => document.querySelector("textarea")?.value === "`README.md` ");
assert.equal(await page.locator(".panel, .peek").count(), 0, "Mention leaves the composer in view");
await page.locator(".panel-button").click();
await page.locator("button.tree-row").first().waitFor();
assert.equal(await page.locator(".peek").count(), 0, "the mentioned file isn't waiting in the panel");
// straight away: Escape is armed as soon as the panel is on screen, not a frame later
await page.keyboard.press("Escape");
await page.locator(".panel").waitFor({ state: "detached", timeout: 2000 });
assert.deepEqual(troubles, [], "the page ran without errors or refusals");
});
// The break this catches: the Review tab's chain (`show_open_review` through the engine to the
// review desk, `load_guided_review` of the working changes, the guide and chapter pieces, and
// `record_review_progress` kept in the session the next ask reads) broken in Safari's engine
test("the review tab reviews the changes and keeps a chapter marked", async () => {
await page.locator(".panel-button").click();
await page.locator('button.tab:has-text("Review")').click();
await page.locator('.panel button.retry:has-text("Review changes")').click();
await page.locator(".rv-target", { hasText: "Working changes" }).waitFor();
await page.locator(".rv-chapter .rv-title").first().click();
await page.locator(".peek .rv-chapter-view .rv-file", { hasText: WRITTEN.path }).waitFor();
await page.locator('.peek button.mention:has-text("Reviewed")').click();
await page.locator('.peek button.mention[aria-pressed="true"]').waitFor();
// Escape closes the chapter, then the panel, as it closes a file and then the panel
await page.keyboard.press("Escape");
await page.locator(".peek").waitFor({ state: "detached" });
await page.keyboard.press("Escape");
await page.locator(".panel").waitFor({ state: "detached", timeout: 2000 });
await page.locator(".panel-button").click();
await page.locator('button.tab:has-text("Review")').click();
// asked afresh, the host's session says which chapter was walked
await page.locator(".rv-chapter .rv-walked").first().waitFor();
await page.keyboard.press("Escape");
assert.deepEqual(troubles, [], "the page ran without errors or refusals");
});
/** Opens README.md from the Files tab, its lines drawn. */
async function openReadme() {
await page.locator(".panel").waitFor({ state: "detached" });
await page.locator(".panel-button").click();
await page.locator('button.tab:has-text("Files")').click();
await page.locator("button.tree-row", { hasText: "README.md" }).click();
await page.locator('.peek .fl[data-line="4"]').waitFor();
}
/** Selects `words` inside line `line` of the open file, as a long press and drag would. */
async function selectWithin(/** @type {number} */ line, /** @type {string} */ words) {
await page.evaluate(([line, words]) => {
const code = document.querySelector(`.peek .fl[data-line="${line}"] code`);
const walker = document.createTreeWalker(/** @type {Node} */ (code), NodeFilter.SHOW_TEXT);
for (let node = walker.nextNode(); node; node = walker.nextNode()) {
const at = node.textContent?.indexOf(String(words)) ?? -1;
if (at < 0) continue;
const range = document.createRange();
range.setStart(node, at);
range.setEnd(node, at + String(words).length);
document.getSelection()?.removeAllRanges();
document.getSelection()?.addRange(range);
return;
}
}, [line, words]);
}
// The break this catches: line picks lost between the host's markup and the composer (rows not
// naming their lines, a tap on a number not picking, a second tap not stretching, picked rows not
// marked), or a selection inside a line, the phone's own way, not offering Ask for that line, or
// Ask writing other words than the TUI sends for the same lines
test("lines picked by number, or selected in part, are asked about in the TUI's words", async () => {
await openReadme();
const number = (/** @type {number} */ line) => page.locator(`.peek .fl[data-line="${line}"] .ln`);
await number(3).click();
await page.locator(".line-ask button", { hasText: "Ask about line 3" }).waitFor();
await number(4).click();
await page.locator(".line-ask button", { hasText: "Ask about lines 3–4" }).waitFor();
assert.equal(await page.locator(".peek .fl.picked").count(), 2, "the picked rows are marked");
await page.locator(".line-ask button").click();
await page.waitForFunction(() => document.querySelector("textarea")?.value.includes("`README.md` lines 3–4"));
assert.equal(await page.locator(".panel, .peek").count(), 0, "Ask leaves the composer in view");
await openReadme();
await selectWithin(3, "4519");
await page.locator(".line-ask button", { hasText: "Ask about line 3" }).click();
await page.waitForFunction(() => document.querySelector("textarea")?.value.includes("`README.md` line 3"));
assert.deepEqual(troubles, [], "the page ran without errors or refusals");
});
/** Writes a comment in the open composer, as a question or not, and saves it unsent. */
async function saveComment(/** @type {string} */ words, question = false) {
if (question) await page.locator(".rv-kinds button", { hasText: "Question" }).click();
await page.locator(".rv-compose textarea").fill(words);
await page.locator(".rv-compose button", { hasText: "Save" }).click();
}
// The break this catches: comments lost between the phone and the review desk (a line pick not
// anchoring to its line, the chapter comment not offered with nothing picked, the desk's saved
// session not redrawn as cards, a card's Delete not reaching the desk, or the guide not counting
// what's unsent)
test("a review chapter takes comments on its lines and on itself, kept by the host", async () => {
await page.locator(".panel").waitFor({ state: "detached" });
await page.locator(".panel-button").click();
await page.locator('button.tab:has-text("Review")').click();
await page.locator(".rv-chapter .rv-title").first().click();
await page.locator('.peek .dl[data-line="1"] .ln').first().click();
await page.locator(".line-ask button", { hasText: /^Comment$/ }).click();
await page.locator(".rv-compose", { hasText: "Comment on line 1" }).waitFor();
await saveComment("Why this file?", true);
const asked = page.locator(".peek .rv-finding", { hasText: "Why this file?" });
await asked.locator(".rv-state", { hasText: "unsent" }).waitFor();
assert.match((await asked.locator(".rv-finding-head").textContent()) ?? "", /question.*line 1/);
await page.locator(".line-ask button", { hasText: "Comment on the chapter" }).click();
await saveComment("Split this up.");
await page.locator(".peek .rv-finding", { hasText: "Split this up." }).waitFor();
await asked.locator('button[data-act="delete"]').click();
await asked.waitFor({ state: "detached" });
await page.keyboard.press("Escape");
await page.locator(".peek").waitFor({ state: "detached" });
await page.locator(".rv-unsent", { hasText: "1 unsent comment" }).waitFor();
await page.keyboard.press("Escape");
assert.deepEqual(troubles, [], "the page ran without errors or refusals");
});
/** Sends `command` from the composer, as typed. */
async function runCommand(/** @type {string} */ command) {
await page.locator(".composer textarea").fill(command);
await page.locator(".send").click();
}
/** The label of the panel tab showing. */
const shownTab = () => page.locator('.panel button.tab[aria-selected="true"]').textContent();
// The break this catches: a phone keeping two header buttons, the panel's button not reaching the
// dock, its tabs wrapping to a second row on the narrowest iPhone, a diff opened from the dock
// drawn under the panel, Escape closing the panel with the diff, or `/dock` on a phone doing
// nothing now the dock lives in the panel
test("on a phone one header button opens the dock and the project", async () => {
await page.locator(".panel").waitFor({ state: "detached" });
await page.setViewportSize({ width: 375, height: 812 });
// no dock button beside the panel's, once the app sees the narrow screen
await page.locator(".dock-toggle").waitFor({ state: "detached", timeout: 2000 });
await page.locator(".panel-button").click();
assert.equal(await shownTab(), "Dock");
const rows = await page.$$eval(".panel button.tab", (tabs) => new Set(tabs.map((tab) => tab.getBoundingClientRect().top)).size);
assert.equal(rows, 1, "the tabs fit one row");
await page.locator(`.panel button.change[data-path="${WRITTEN.path}"]`).click();
await page.locator(".peek .dl-addition").waitFor();
const onTop = await page.evaluate(() => document.elementFromPoint(innerWidth / 2, innerHeight / 2)?.closest(".peek") !== null);
assert.ok(onTop, "the diff covers the panel");
await page.keyboard.press("Escape");
await page.locator(".peek").waitFor({ state: "detached" });
assert.equal(await page.locator(".panel").count(), 1, "the diff took the Escape, not the panel");
await page.keyboard.press("Escape");
await page.locator(".panel").waitFor({ state: "detached", timeout: 2000 });
await runCommand("/dock");
assert.equal(await shownTab(), "Dock");
await page.locator(".panel .close").click();
await page.setViewportSize(playwright.devices["iPad Pro 11 landscape"].viewport);
assert.deepEqual(troubles, [], "the page ran without errors or refusals");
});

View File

@@ -0,0 +1,117 @@
// A Luxe of the test's own: a session in a fresh git project, driven by the mock model, and a
// bridge serving it, all under one temporary directory, so nothing touches the real config.
import { spawn, execFileSync } from "node:child_process";
import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
import { createServer } from "node:net";
import { tmpdir } from "node:os";
import { dirname, join, resolve } from "node:path";
import { createInterface } from "node:readline";
import { fileURLToPath } from "node:url";
const REPO = resolve(dirname(fileURLToPath(import.meta.url)), "../../../..");
/** The tailnet login the bridge lets in, sent as Tailscale Serve would send it. */
export const LOGIN = "e2e@luxe.test";
/** The `luxe` to test: `LUXE_BIN`, or the debug build. */
const LUXE = process.env.LUXE_BIN ?? join(REPO, "target/debug/luxe");
/** Starts a session and a bridge for the mock model on `modelPort`. */
export async function startHost(modelPort) {
const root = mkdtempSync(join(tmpdir(), "luxe-e2e-"));
const env = isolatedEnv(root);
const project = gitProject(root);
writeConfig(env.LUXE_CONFIG_DIR, modelPort);
const children = [];
const host = { root, project, children, stop: () => stop(host) };
host.sessionId = await startSession(env, project, children);
host.invitation = invite(env);
host.url = await startBridge(env, children);
return host;
}
function isolatedEnv(root) {
const dirs = { LUXE_CONFIG_DIR: "config", LUXE_STATE_DIR: "state", LUXE_RUNTIME_DIR: "run", XDG_CACHE_HOME: "cache" };
/** @type {NodeJS.ProcessEnv} */
const env = { ...process.env, LUXE_MODELS_DEV_REFRESH: "0", HOME: join(root, "home") };
for (const [name, dir] of Object.entries(dirs)) mkdirSync((env[name] = join(root, dir)), { recursive: true });
return env;
}
function gitProject(root) {
const project = join(root, "project");
mkdirSync(project);
const git = (...args) => execFileSync("git", ["-c", "user.name=e2e", "-c", "user.email=e2e@luxe.test", ...args], { cwd: project });
git("init", "-q");
// a few lines, so a phone can pick a range of them and select part of one
writeFileSync(join(project, "README.md"), "# e2e\n\nThe port is 4519.\nThe host is luxe.local.\n");
git("add", ".");
git("commit", "-qm", "start");
return project;
}
// The mock model, and a rule that stops its write for a permission the phone has to grant
function writeConfig(configDir, port) {
const models = {
providers: { mock: { base_url: `http://127.0.0.1:${port}/v1`, api_key: "unused", api: "openai-completions" } },
models: { "mock/scripted": { name: "Scripted", context_window: 32000, max_tokens: 4000 } },
};
writeFileSync(join(configDir, "models.json"), JSON.stringify(models));
writeFileSync(join(configDir, "permissions.json"), JSON.stringify({ permission: { edit: "ask" } }));
}
// `--rpc` keeps the session while its stdin is open, and its `ready` event names it. Its events
// keep being read after that, so a full pipe never stalls it.
function startSession(env, project, children) {
const luxe = spawn(LUXE, ["--rpc", "--model", "mock/scripted"], { cwd: project, env, stdio: ["pipe", "pipe", "inherit"] });
children.push(luxe);
return new Promise((ready, failed) => {
createInterface({ input: luxe.stdout }).on("line", (line) => {
const event = JSON.parse(line);
if (event.kind === "ready") ready(event.content.session_id);
});
luxe.once("exit", (code) => failed(new Error(`luxe --rpc exited (${code}) before it was ready`)));
});
}
// The token is the link's fragment, or printed on its own where Tailscale can't name the machine
function invite(env) {
const out = execFileSync(LUXE, ["remote", "pair"], { env, encoding: "utf8" });
const token = /#([\w-]+)/.exec(out)?.[1];
if (!token) throw new Error(`no invitation in: ${out}`);
return token;
}
async function startBridge(env, children) {
const port = await freePort();
const bridge = spawn(LUXE, ["remote", "--port", String(port), "--allow", LOGIN], { env, stdio: "inherit" });
children.push(bridge);
const url = `http://127.0.0.1:${port}`;
await until(() => fetch(url).then(() => true, () => false), "the bridge to listen");
return url;
}
function freePort() {
return new Promise((done) => {
const probe = createServer().listen(0, "127.0.0.1", () => {
const { port } = /** @type {import("node:net").AddressInfo} */ (probe.address());
probe.close(() => done(port));
});
});
}
/** Polls `check` until it's true, for at most ten seconds. */
export async function until(check, what) {
for (let tries = 0; tries < 100; tries += 1) {
if (await check()) return;
await new Promise((done) => setTimeout(done, 100));
}
throw new Error(`timed out waiting for ${what}`);
}
async function stop(host) {
for (const child of host.children) child.kill();
await Promise.all(host.children.map((child) => child.exitCode ?? new Promise((done) => child.once("exit", done))));
rmSync(host.root, { recursive: true, force: true });
}

View File

@@ -0,0 +1,62 @@
// A model that follows a script, served the way an OpenAI-compatible endpoint streams: asked to
// act, it calls `write`; given the tool's result, it says what it did. A request with no tools
// (a session title, say) gets a word back. Every request is kept for the test to look at.
import { createServer } from "node:http";
/** The file the scripted model writes, and what it writes in it. */
export const WRITTEN = { path: "hello.txt", content: "hello from the mock\n" };
/** Starts the server on a free port. */
export async function startMockProvider() {
const requests = [];
const server = createServer((request, response) => answer(request, response, requests));
await new Promise((resolve) => server.listen(0, "127.0.0.1", () => resolve(undefined)));
const { port } = /** @type {import("node:net").AddressInfo} */ (server.address());
return { port, requests, close: () => new Promise((resolve) => server.close(resolve)) };
}
async function answer(request, response, requests) {
if (request.method !== "POST" || !request.url?.endsWith("/chat/completions")) {
response.writeHead(404).end();
return;
}
const body = JSON.parse(await readBody(request));
requests.push(body);
response.writeHead(200, { "content-type": "text/event-stream" });
for (const chunk of reply(body)) response.write(`data: ${JSON.stringify(chunk)}\n\n`);
response.end("data: [DONE]\n\n");
}
async function readBody(request) {
let text = "";
for await (const part of request) text += part;
return text;
}
function reply(body) {
if (!body.tools?.length) return words("Mock");
if (body.messages.at(-1)?.role === "tool") return words(`Wrote **${WRITTEN.path}**.`);
return writeCall();
}
const chunk = (delta, finish = null) => ({
id: "mock", object: "chat.completion.chunk", created: 0, model: "scripted",
choices: [{ index: 0, delta, finish_reason: finish }],
});
const usage = { id: "mock", object: "chat.completion.chunk", created: 0, model: "scripted", choices: [],
usage: { prompt_tokens: 1200, completion_tokens: 20, total_tokens: 1220 } };
function words(text) {
const half = Math.ceil(text.length / 2);
return [chunk({ role: "assistant", content: text.slice(0, half) }), chunk({ content: text.slice(half) }),
chunk({}, "stop"), usage];
}
function writeCall() {
const call = { index: 0, id: "call_write", type: "function", function: { name: "write", arguments: "" } };
const args = { index: 0, function: { arguments: JSON.stringify(WRITTEN) } };
return [chunk({ role: "assistant", content: null, tool_calls: [call] }), chunk({ tool_calls: [args] }),
chunk({}, "tool_calls"), usage];
}