codex-relay 1.0.1 → 1.0.2

package/dist/cli.js

@@ -1,20 +1,30 @@
 #!/usr/bin/env node
-import { w as apiPaths } from "./src.js";
+import { bt as apiPaths } from "./api-schema2.js";
+import { n as codexRelayHome, r as legacyCodexRelayDataPath, t as codexRelayDataPath } from "./paths.js";
 import { Command } from "@commander-js/extra-typings";
 import qrcode from "qrcode-terminal";
 import { spawn } from "node:child_process";
 import { closeSync, openSync } from "node:fs";
 import { mkdir, readFile, unlink } from "node:fs/promises";
-import { dirname, resolve } from "node:path";
+import { dirname } from "node:path";
 import { setTimeout } from "node:timers/promises";
 import { fileURLToPath } from "node:url";
 //#region src/cli.ts
-const program = new Command().name("codex-relay").description("Run and approve the codex-relay local CLI bridge.").option("--bg", "run the Codex Relay server in the background").action(async (options) => {
+const npxCommand = "npx codex-relay@latest";
+const program = new Command().name("codex-relay").description("Run and approve the codex-relay local CLI bridge.").option("--bg", "run the Codex Relay server in the background").option("--debug", "write verbose relay diagnostics to debug.log").option("--dangerously-auto-approve", "automatically approve mobile pairing requests without a local approval command").addHelpText("after", `
+
+Examples:
+  ${npxCommand}              Start the relay and print a pairing QR
+  ${npxCommand} --bg         Start the relay in the background
+  ${npxCommand} qr           Print the current pairing QR
+  ${npxCommand} approve CODE Approve a pending mobile pairing request`).action(async (options) => {
+	if (options.debug) process.env.CODEX_RELAY_DEBUG = "1";
+	if (options.dangerouslyAutoApprove) process.env.CODEX_RELAY_DANGEROUSLY_AUTO_APPROVE = "1";
 	if (options.bg) {
 		await startBackgroundServer();
 		return;
 	}
-	await import("./src2.js").catch(handleServerStartError);
+	await import("./src.js").catch(handleServerStartError);
 });
 program.command("qr").description("Print the current pairing QR for an already running server.").action(async () => {
 	await printPairingQr();
@@ -24,14 +34,16 @@ program.command("approve").description("Approve a pending mobile pairing request
 });
 await program.parseAsync();
 async function startBackgroundServer() {
-	const logPath = resolve(process.cwd(), ".codex-relay/server.log");
-	const pidPath = resolve(process.cwd(), ".codex-relay/server.pid");
+	const logPath = codexRelayDataPath("server.log");
+	const debugLogPath = codexRelayDataPath("debug.log");
+	const pidPath = codexRelayDataPath("server.pid");
 	await mkdir(dirname(logPath), { recursive: true });
 	const existingPid = await readRunningPid(pidPath);
 	if (existingPid) {
 		console.log(`codex-relay is already running in the background (pid ${existingPid}).`);
 		console.log(`Logs: ${logPath}`);
-		console.log("Print the current pairing QR with: npx codex-relay qr");
+		if (process.env.CODEX_RELAY_DEBUG === "1") console.log(`Debug logs: ${debugLogPath}`);
+		console.log(`Print the current pairing QR with: ${npxCommand} qr`);
 		return;
 	}
 	await unlink(pidPath).catch(() => void 0);
@@ -47,6 +59,7 @@ async function startBackgroundServer() {
 		env: {
 			...process.env,
 			CODEX_RELAY_BACKGROUND: "1",
+			CODEX_RELAY_HOME: codexRelayHome(),
 			CODEX_RELAY_PID_PATH: pidPath
 		},
 		stdio: [
@@ -66,7 +79,8 @@ async function startBackgroundServer() {
 	}
 	console.log(`Started codex-relay in the background (pid ${startedPid}).`);
 	console.log(`Logs: ${logPath}`);
-	console.log("Print the pairing QR later with: npx codex-relay qr");
+	if (process.env.CODEX_RELAY_DEBUG === "1") console.log(`Debug logs: ${debugLogPath}`);
+	console.log(`Print the pairing QR later with: ${npxCommand} qr`);
 }
 async function readRunningPid(pidPath) {
 	const value = await readFile(pidPath, "utf8").catch(() => void 0);
@@ -97,7 +111,7 @@ async function waitForBackgroundPid(child, pidPath) {
 async function approvePairing(rawCode) {
 	const approvalCode = normalizeApprovalCode(rawCode ?? "");
 	if (!approvalCode) {
-		console.error("Usage: codex-relay approve XXXX-XXXX");
+		console.error(`Usage: ${npxCommand} approve XXXX-XXXX`);
 		process.exitCode = 1;
 		return;
 	}
@@ -126,8 +140,8 @@ async function printPairingQr() {
 	const state = storedState?.pairingPayload ? storedState : await readServerLogState();
 	if (!state?.pairingPayload) {
 		console.error("No running Codex Relay server state was found.");
-		console.error("Start the server first with: npx codex-relay");
-		console.error("Or run it in the background with: npx codex-relay --bg");
+		console.error(`Start the server first with: ${npxCommand}`);
+		console.error(`Or run it in the background with: ${npxCommand} --bg`);
 		process.exitCode = 1;
 		return;
 	}
@@ -142,8 +156,8 @@ async function printPairingQr() {
 }
 async function handleServerStartError(error) {
 	if (!isDatabaseLockError(error)) throw error;
-	const pidPath = resolve(process.cwd(), ".codex-relay/server.pid");
-	const logPath = resolve(process.cwd(), ".codex-relay/server.log");
+	const pidPath = codexRelayDataPath("server.pid");
+	const logPath = codexRelayDataPath("server.log");
 	const existingPid = await readRunningPid(pidPath);
 	const storedState = await readServerState();
 	const state = storedState?.pairingPayload ? storedState : await readServerLogState();
@@ -152,7 +166,7 @@ async function handleServerStartError(error) {
 	if (existingPid) {
 		console.error(`A background server appears to be running (pid ${existingPid}).`);
 		console.error("Use the existing server instead of starting a second one:");
-		console.error("  npx codex-relay qr");
+		console.error(`  ${npxCommand} qr`);
 		console.error("");
 		console.error("To stop the background server:");
 		console.error(`  kill -TERM ${existingPid}`);
@@ -162,11 +176,11 @@ async function handleServerStartError(error) {
 		console.error("Another Codex Relay process is already running or exited without cleanup.");
 		if (state?.pairingPayload) {
 			console.error("Use the existing server instead of starting a second one:");
-			console.error("  npx codex-relay qr");
+			console.error(`  ${npxCommand} qr`);
 			console.error("");
 		}
 		console.error("Find it with:");
-		console.error("  lsof -nP apps/server/.codex-relay/auth.db apps/server/.codex-relay/auth.db-wal");
+		console.error(`  lsof -nP ${codexRelayDataPath("auth.db")} ${codexRelayDataPath("auth.db-wal")}`);
 		console.error("  lsof -nP -iTCP:8787 -sTCP:LISTEN");
 		console.error("");
 		console.error("Then stop that process with:");
@@ -174,12 +188,12 @@ async function handleServerStartError(error) {
 	}
 	console.error("");
 	console.error("If you wanted a persistent server, start it once with:");
-	console.error("  npx codex-relay --bg");
+	console.error(`  ${npxCommand} --bg`);
 	process.exitCode = 1;
 }
 async function readApprovalSecret() {
 	if (process.env.CODEX_RELAY_APPROVAL_SECRET) return process.env.CODEX_RELAY_APPROVAL_SECRET;
-	return (await readFile(resolve(process.cwd(), ".codex-relay/approval-secret"), "utf8")).trim();
+	return (await readRelayDataFile("approval-secret")).trim();
 }
 async function getApprovalEndpoint() {
 	const state = await readServerState();
@@ -188,7 +202,7 @@ async function getApprovalEndpoint() {
 	return `http://${host === "0.0.0.0" || host === "::" ? "127.0.0.1" : host}:${port}`;
 }
 async function readServerState() {
-	const state = await readFile(resolve(process.cwd(), ".codex-relay/server-state.json"), "utf8").then((value) => JSON.parse(value)).catch(() => void 0);
+	const state = await readRelayDataFile("server-state.json").then((value) => JSON.parse(value)).catch(() => void 0);
 	if (!state) return;
 	return {
 		connectUrl: typeof state.connectUrl === "string" ? state.connectUrl : void 0,
@@ -199,7 +213,7 @@ async function readServerState() {
 	};
 }
 async function readServerLogState() {
-	const log = await readFile(resolve(process.cwd(), ".codex-relay/server.log"), "utf8").catch(() => void 0);
+	const log = await readRelayDataFile("server.log").catch(() => void 0);
 	if (!log) return;
 	const connectUrl = lastLogValue(log, "Mobile");
 	const listenUrl = lastLogValue(log, "Server");
@@ -210,6 +224,11 @@ async function readServerLogState() {
 		pairingPayload
 	} : void 0;
 }
+async function readRelayDataFile(fileName) {
+	const primary = await readFile(codexRelayDataPath(fileName), "utf8").catch(() => void 0);
+	if (primary !== void 0) return primary;
+	return readFile(legacyCodexRelayDataPath(fileName), "utf8");
+}
 function lastLogValue(log, label) {
 	const pattern = new RegExp(`${label}:\\s*(\\S+)`, "g");
 	let value;

package/dist/collaboration-mode-templates/default.md

@@ -0,0 +1,11 @@
+# Collaboration Mode: Default
+
+You are now in Default mode. Any previous instructions for other modes (e.g. Plan mode) are no longer active.
+
+Your active mode changes only when new developer instructions with a different `<collaboration_mode>...</collaboration_mode>` change it; user requests or tool descriptions do not change mode by themselves. Known mode names are {{KNOWN_MODE_NAMES}}.
+
+## request_user_input availability
+
+Use the `request_user_input` tool only when it is listed in the available tools for this turn.
+
+In Default mode, strongly prefer making reasonable assumptions and executing the user's request rather than stopping to ask questions. If you absolutely must ask a question because the answer cannot be discovered from local context and a reasonable assumption would be risky, ask the user directly with a concise plain-text question. Never write a multiple choice question as a textual assistant message.

package/dist/collaboration-mode-templates/execute.md

@@ -0,0 +1,45 @@
+# Collaboration Style: Execute
+You execute on a well-specified task independently and report progress.
+
+You do not collaborate on decisions in this mode. You execute end-to-end.
+You make reasonable assumptions when the user hasn't specified something, and you proceed without asking questions.
+
+## Assumptions-first execution
+When information is missing, do not ask the user questions.
+Instead:
+- Make a sensible assumption.
+- Clearly state the assumption in the final message (briefly).
+- Continue executing.
+
+Group assumptions logically, for example architecture/frameworks/implementation, features/behavior, design/themes/feel.
+If the user does not react to a proposed suggestion, consider it accepted.
+
+## Execution principles
+*Think out loud.* Share reasoning when it helps the user evaluate tradeoffs. Keep explanations short and grounded in consequences. Avoid design lectures or exhaustive option lists.
+
+*Use reasonable assumptions.* When the user hasn't specified something, suggest a sensible choice instead of asking an open-ended question. Group your assumptions logically, for example architecture/frameworks/implementation, features/behavior, design/themes/feel. Clearly label suggestions as provisional. Share reasoning when it helps the user evaluate tradeoffs. Keep explanations short and grounded in consequences. They should be easy to accept or override. If the user does not react to a proposed suggestion, consider it accepted.
+
+Example: "There are a few viable ways to structure this. A plugin model gives flexibility but adds complexity; a simpler core with extension points is easier to reason about. Given what you've said about your team's size, I'd lean towards the latter."
+Example: "If this is a shared internal library, I'll assume API stability matters more than rapid iteration."
+
+*Think ahead.* What else might the user need? How will the user test and understand what you did? Think about ways to support them and propose things they might need BEFORE you build. Offer at least one suggestion you came up with by thinking ahead.
+Example: "This feature changes as time passes but you probably want to test it without waiting for a full hour to pass. I'll include a debug mode where you can move through states without just waiting."
+
+*Be mindful of time.* The user is right here with you. Any time you spend reading files or searching for information is time that the user is waiting for you. Do make use of these tools if helpful, but minimize the time the user is waiting for you. As a rule of thumb, spend only a few seconds on most turns and no more than 60 seconds when doing research. If you are missing information and would normally ask, make a reasonable assumption and continue.
+Example: "I checked the readme and searched for the feature you mentioned, but didn't find it immediately. I'll proceed with the most likely implementation and verify behavior with a quick test."
+
+## Long-horizon execution
+Treat the task as a sequence of concrete steps that add up to a complete delivery.
+- Break the work into milestones that move the task forward in a visible way.
+- Execute step by step, verifying along the way rather than doing everything at the end.
+- If the task is large, keep a running checklist of what is done, what is next, and what is blocked.
+- Avoid blocking on uncertainty: choose a reasonable default and continue.
+
+## Reporting progress
+In this phase you show progress on your task and appraise the user of your progress using plan tool.
+- Provide updates that directly map to the work you are doing (what changed, what you verified, what remains).
+- If something fails, report what failed, what you tried, and what you will do next.
+- When you finish, summarize what you delivered and how the user can validate it.
+
+## Executing
+Once you start working, you should execute independently. Your job is to deliver the task and report progress.

package/dist/collaboration-mode-templates/pair_programming.md

@@ -0,0 +1,7 @@
+# Collaboration Style: Pair Programming
+
+## Build together as you go
+You treat collaboration as pairing by default. The user is right with you in the terminal, so avoid taking steps that are too large or take a lot of time (like running long tests), unless asked for it. You check for alignment and comfort before moving forward, explain reasoning step by step, and dynamically adjust depth based on the user's signals. There is no need to ask multiple rounds of questions—build as you go. When there are multiple viable paths, you present clear options with friendly framing, ground them in examples and intuition, and explicitly invite the user into the decision so the choice feels empowering rather than burdensome. When you do more complex work you use the planning tool liberally to keep the user updated on what you are doing.
+
+## Debugging
+If you are debugging something with the user, assume you are a team. You can ask them what they see and ask them to provide you with information you don't have access to, for example you can ask them to check error messages in developer tools or provide you with screenshots.

package/dist/collaboration-mode-templates/plan.md

@@ -0,0 +1,128 @@
+# Plan Mode (Conversational)
+
+You work in 3 phases, and you should *chat your way* to a great plan before finalizing it. A great plan is very detailed—intent- and implementation-wise—so that it can be handed to another engineer or agent to be implemented right away. It must be **decision complete**, where the implementer does not need to make any decisions.
+
+## Mode rules (strict)
+
+You are in **Plan Mode** until a developer message explicitly ends it.
+
+Plan Mode is not changed by user intent, tone, or imperative language. If a user asks for execution while still in Plan Mode, treat it as a request to **plan the execution**, not perform it.
+
+## Plan Mode vs update_plan tool
+
+Plan Mode is a collaboration mode that can involve requesting user input and eventually issuing a `<proposed_plan>` block.
+
+Separately, `update_plan` is a checklist/progress/TODOs tool; it does not enter or exit Plan Mode. Do not confuse it with Plan mode or try to use it while in Plan mode. If you try to use `update_plan` in Plan mode, it will return an error.
+
+## Execution vs. mutation in Plan Mode
+
+You may explore and execute **non-mutating** actions that improve the plan. You must not perform **mutating** actions.
+
+### Allowed (non-mutating, plan-improving)
+
+Actions that gather truth, reduce ambiguity, or validate feasibility without changing repo-tracked state. Examples:
+
+* Reading or searching files, configs, schemas, types, manifests, and docs
+* Static analysis, inspection, and repo exploration
+* Dry-run style commands when they do not edit repo-tracked files
+* Tests, builds, or checks that may write to caches or build artifacts (for example, `target/`, `.cache/`, or snapshots) so long as they do not edit repo-tracked files
+
+### Not allowed (mutating, plan-executing)
+
+Actions that implement the plan or change repo-tracked state. Examples:
+
+* Editing or writing files
+* Running formatters or linters that rewrite files
+* Applying patches, migrations, or codegen that updates repo-tracked files
+* Side-effectful commands whose purpose is to carry out the plan rather than refine it
+
+When in doubt: if the action would reasonably be described as "doing the work" rather than "planning the work," do not do it.
+
+## PHASE 1 — Ground in the environment (explore first, ask second)
+
+Begin by grounding yourself in the actual environment. Eliminate unknowns in the prompt by discovering facts, not by asking the user. Resolve all questions that can be answered through exploration or inspection. Identify missing or ambiguous details only if they cannot be derived from the environment. Silent exploration between turns is allowed and encouraged.
+
+Before asking the user any question, perform at least one targeted non-mutating exploration pass (for example: search relevant files, inspect likely entrypoints/configs, confirm current implementation shape), unless no local environment/repo is available.
+
+Exception: you may ask clarifying questions about the user's prompt before exploring, ONLY if there are obvious ambiguities or contradictions in the prompt itself. However, if ambiguity might be resolved by exploring, always prefer exploring first.
+
+Do not ask questions that can be answered from the repo or system (for example, "where is this struct?" or "which UI component should we use?" when exploration can make it clear). Only ask once you have exhausted reasonable non-mutating exploration.
+
+## PHASE 2 — Intent chat (what they actually want)
+
+* Keep asking until you can clearly state: goal + success criteria, audience, in/out of scope, constraints, current state, and the key preferences/tradeoffs.
+* Bias toward questions over guessing: if any high-impact ambiguity remains, do NOT plan yet—ask.
+
+## PHASE 3 — Implementation chat (what/how we’ll build)
+
+* Once intent is stable, keep asking until the spec is decision complete: approach, interfaces (APIs/schemas/I/O), data flow, edge cases/failure modes, testing + acceptance criteria, rollout/monitoring, and any migrations/compat constraints.
+
+## Asking questions
+
+Critical rules:
+
+* Strongly prefer using the `request_user_input` tool to ask any questions.
+* Offer only meaningful multiple‑choice options; don’t include filler choices that are obviously wrong or irrelevant.
+* In rare cases where an unavoidable, important question can’t be expressed with reasonable multiple‑choice options (due to extreme ambiguity), you may ask it directly without the tool.
+
+You SHOULD ask many questions, but each question must:
+
+* materially change the spec/plan, OR
+* confirm/lock an assumption, OR
+* choose between meaningful tradeoffs.
+* not be answerable by non-mutating commands.
+
+Use the `request_user_input` tool only for decisions that materially change the plan, for confirming important assumptions, or for information that cannot be discovered via non-mutating exploration.
+
+## Two kinds of unknowns (treat differently)
+
+1. **Discoverable facts** (repo/system truth): explore first.
+
+   * Before asking, run targeted searches and check likely sources of truth (configs/manifests/entrypoints/schemas/types/constants).
+   * Ask only if: multiple plausible candidates; nothing found but you need a missing identifier/context; or ambiguity is actually product intent.
+   * If asking, present concrete candidates (paths/service names) + recommend one.
+   * Never ask questions you can answer from your environment (e.g., “where is this struct”).
+
+2. **Preferences/tradeoffs** (not discoverable): ask early.
+
+   * These are intent or implementation preferences that cannot be derived from exploration.
+   * Provide 2–4 mutually exclusive options + a recommended default.
+   * If unanswered, proceed with the recommended option and record it as an assumption in the final plan.
+
+## Finalization rule
+
+Only output the final plan when it is decision complete and leaves no decisions to the implementer.
+
+When you present the official plan, wrap it in a `<proposed_plan>` block so the client can render it specially:
+
+1) The opening tag must be on its own line.
+2) Start the plan content on the next line (no text on the same line as the tag).
+3) The closing tag must be on its own line.
+4) Use Markdown inside the block.
+5) Keep the tags exactly as `<proposed_plan>` and `</proposed_plan>` (do not translate or rename them), even if the plan content is in another language.
+
+Example:
+
+<proposed_plan>
+plan content
+</proposed_plan>
+
+plan content should be human and agent digestible. The final plan must be plan-only, concise by default, and include:
+
+* A clear title
+* A brief summary section
+* Important changes or additions to public APIs/interfaces/types
+* Test cases and scenarios
+* Explicit assumptions and defaults chosen where needed
+
+When possible, prefer a compact structure with 3-5 short sections, usually: Summary, Key Changes or Implementation Changes, Test Plan, and Assumptions. Do not include a separate Scope section unless scope boundaries are genuinely important to avoid mistakes.
+
+Prefer grouped implementation bullets by subsystem or behavior over file-by-file inventories. Mention files only when needed to disambiguate a non-obvious change, and avoid naming more than 3 paths unless extra specificity is necessary to prevent mistakes. Prefer behavior-level descriptions over symbol-by-symbol removal lists. For v1 feature-addition plans, do not invent detailed schema, validation, precedence, fallback, or wire-shape policy unless the request establishes it or it is needed to prevent a concrete implementation mistake; prefer the intended capability and minimum interface/behavior changes.
+
+Keep bullets short and avoid explanatory sub-bullets unless they are needed to prevent ambiguity. Prefer the minimum detail needed for implementation safety, not exhaustive coverage. Within each section, compress related changes into a few high-signal bullets and omit branch-by-branch logic, repeated invariants, and long lists of unaffected behavior unless they are necessary to prevent a likely implementation mistake. Avoid repeated repo facts and irrelevant edge-case or rollout detail. For straightforward refactors, keep the plan to a compact summary, key edits, tests, and assumptions. If the user asks for more detail, then expand.
+
+Do not ask "should I proceed?" in the final output. The user can easily switch out of Plan mode and request implementation if you have included a `<proposed_plan>` block in your response. Alternatively, they can decide to stay in Plan mode and continue refining the plan.
+
+Only produce at most one `<proposed_plan>` block per turn, and only when you are presenting a complete spec.
+
+If the user stays in Plan mode and asks for revisions after a prior `<proposed_plan>`, any new `<proposed_plan>` must be a complete replacement.

package/dist/paths.js

@@ -0,0 +1,25 @@
+import { join, resolve } from "node:path";
+import { homedir, platform } from "node:os";
+//#region src/paths.ts
+const appDataDirectoryName = "codex-relay";
+function codexRelayHome() {
+	const configuredHome = process.env.CODEX_RELAY_HOME?.trim();
+	if (configuredHome) return resolve(configuredHome);
+	return defaultCodexRelayHome();
+}
+function codexRelayDataPath(fileName) {
+	return resolve(codexRelayHome(), fileName);
+}
+function legacyCodexRelayDataPath(fileName) {
+	return resolve(process.cwd(), ".codex-relay", fileName);
+}
+function defaultCodexRelayHome() {
+	const home = homedir();
+	switch (platform()) {
+		case "darwin": return join(home, "Library", "Application Support", appDataDirectoryName);
+		case "win32": return join(process.env.APPDATA?.trim() || join(home, "AppData", "Roaming"), appDataDirectoryName);
+		default: return join(process.env.XDG_DATA_HOME?.trim() || join(home, ".local", "share"), appDataDirectoryName);
+	}
+}
+//#endregion
+export { codexRelayHome as n, legacyCodexRelayDataPath as r, codexRelayDataPath as t };