A local-first multi-agent app development platform, built on PenguinHarness
/**
* The CLI's server client: connection resolution, Bearer-token auth, JSON requests, and
* a dependency-free fetch-based SSE consumer (the HMR deploy path bundles this file with
* esbuild, so everything here rides on globals — fetch above all).
*
* Connection resolution order (first hit wins):
* 1. `--server <url>` — an explicit target. A non-loopback URL requires
* ADELIE_API_TOKEN: the on-disk token file belongs to the LOCAL data root and must
* never be sent to a remote host.
* 2. `ADELIE_API_URL` — the same, from the environment. Server-driven sessions inject
* it (with ADELIE_API_TOKEN) into tool subprocesses, which is how an agent's own
* `penguin` calls find the server that runs them.
* 3. A live `server.lock` at the data root (ADELIE_HOME or ~/.adelie/data): attach to
* the running local server on `http://localhost:<port>`.
* 4. Auto-start: spawn a detached `node <cli entry> server` with PORT=0, wait for its
* lock, attach. The loser of a two-CLI spawn race exits with code 3 ("already
* running"), which the lock poll absorbs — it finds the winner's lock either way.
*
* Token resolution: ADELIE_API_TOKEN, else `<root>/api-token` (written by the server
* each boot). A 401 with a file-sourced token re-reads the file once and retries — the
* server may have restarted (and rotated the token) since the first read.
*
* A 403 `human_required` — a write the server takes only from a person's sign-in, such as
* those that change an Agent's exposure — retries the same request once as the person's
* stored sign-in (`<root>/cli-session.json`, written by `penguin auth login` or
* `penguin auth token`), sent as the `penguin_session` cookie in place of the token. Only for
* a loopback target, only for a sign-in made to a loopback server, and only outside a Session
* (ADELIE_SESSION_ID unset): inside one the command is an Agent's, and the refusal is the
* point. Every other request goes exactly as above.
*/
import { spawn } from "node:child_process";
import fs from "node:fs";
import path from "node:path";
import { resolveRoot } from "@adelie/core";
import { liveServerLock } from "@adelie/server/lock";
import { readSession } from "./auth-session.js";
import type { Messages } from "./i18n.js";
/** Session-id shape (core's convention); a full id needs no directory search. */
const SESSION_ID_RE = /^session-\d{4}-\d{2}-\d{2}-\d{2}-\d{2}-\d{2}-[0-9a-f]{8}$/;
/** Hosts that count as this machine for token-file purposes. */
const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1", "[::1]"]);
/** How the auth token was obtained; decides whether a 401 retries after re-reading the file. */
export type TokenSource = "env" | "file" | "none";
/** The server's session cookie (auth/middleware.ts SESSION_COOKIE): a stored sign-in goes as it. */
const SESSION_COOKIE = "penguin_session";
/** The server's refusal of the local API token on a write only a person may make (requireHuman). */
const HUMAN_REQUIRED = "human_required";
export interface Connection {
/** Normalized base URL, no trailing slash. */
baseUrl: string;
/** Data root used for the token file and the lock (resolution-time value). */
root: string;
/** Whether this call auto-started the server (surfaced to the user on stderr). */
autoStarted: boolean;
/** Whether the target host is loopback (gates the file-token fallback). */
loopback: boolean;
}
/** One parsed SSE frame; `data` is the raw payload (possibly multi-line joined). */
export interface SseFrame {
id?: string;
event?: string;
data: string;
}
export function isLoopbackUrl(url: URL): boolean {
return LOOPBACK_HOSTS.has(url.hostname.toLowerCase());
}
/** Strips trailing slashes and validates the scheme; throws a localized error on junk. */
export function normalizeServerUrl(raw: string, t: Messages): URL {
let url: URL;
try {
url = new URL(raw.trim());
} catch {
throw new Error(t.client.invalidServerUrl(raw));
}
if (url.protocol !== "http:" && url.protocol !== "https:") {
throw new Error(t.client.invalidServerUrl(raw));
}
return url;
}
/** The token file the server writes each boot (kept in sync with the server's auth/api-token.ts). */
export function apiTokenPath(root: string): string {
return path.join(root, "api-token");
}
function readTokenFile(root: string): string | null {
try {
const value = fs.readFileSync(apiTokenPath(root), "utf8").trim();
return value === "" ? null : value;
} catch {
return null;
}
}
/**
* The person's stored sign-in on this data root, for the one retry after a `human_required`
* refusal (see the module doc); null inside a Session, where the command is an Agent's, and for a
* sign-in to a server elsewhere, whose session must not be sent to this one.
*/
function readStoredSignIn(root: string): string | null {
if (process.env.ADELIE_SESSION_ID?.trim()) return null;
const session = readSession(root);
if (session === null) return null;
try {
return isLoopbackUrl(new URL(session.server)) ? session.token : null;
} catch {
return null;
}
}
/** The error code of a JSON error body (`{error: {code}}`), or null for any other body. */
async function errorCodeOf(res: Response): Promise<string | null> {
try {
const body = (await res.json()) as { error?: { code?: unknown } } | null;
return typeof body?.error?.code === "string" ? body.error.code : null;
} catch {
return null;
}
}
/**
* The CLI entry script for auto-start, or null when this process cannot re-run itself
* with plain node (a tsx dev run has a .ts entry) — same rule as serve.ts's cliEntryFor.
*/
export function autoStartEntry(argv1: string | undefined): string | null {
if (!argv1) return null;
return /\.(js|mjs|cjs)$/i.test(argv1) ? path.resolve(argv1) : null;
}
/** yyyy-mm-dd of the local clock (log file naming). */
function localDate(d = new Date()): string {
const pad = (n: number) => (n < 10 ? `0${n}` : `${n}`);
return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
}
/**
* Spawns a detached local server (PORT=0 → ephemeral port), logs to
* `<root>/logs/server-auto-<date>.log`, and waits for a live lock on the root. The lock
* poll accepts ANY live server on the root: if a concurrent CLI won the spawn race, our
* child exits 3 and the winner's lock satisfies the wait just the same.
*/
export async function autoStartServer(
root: string,
t: Messages,
opts: { timeoutMs?: number } = {},
): Promise<{ port: number; logPath: string }> {
const entry = autoStartEntry(process.argv[1]);
if (entry === null) throw new Error(t.client.autoStartUnavailable());
fs.mkdirSync(path.join(root, "logs"), { recursive: true });
const logPath = path.join(root, "logs", `server-auto-${localDate()}.log`);
const fd = fs.openSync(logPath, "a");
let child: ReturnType<typeof spawn>;
try {
child = spawn(process.execPath, [entry, "server"], {
detached: true,
stdio: ["ignore", fd, fd],
env: { ...process.env, PORT: "0" },
});
} finally {
fs.closeSync(fd);
}
let exitCode: number | null = null;
child.on("error", () => {
exitCode = -1;
});
child.on("exit", (code) => {
exitCode = code ?? -1;
});
child.unref();
const deadline = Date.now() + (opts.timeoutMs ?? 20_000);
for (;;) {
const lock = await liveServerLock(root);
if (lock !== null) return { port: lock.port, logPath };
// Exit 3 = "another server owns this root" — the race's loser; keep polling for the
// winner's lock. Any other exit is a startup failure: point at the log.
if (exitCode !== null && exitCode !== 3) {
throw new Error(t.client.autoStartFailed(logPath));
}
if (Date.now() >= deadline) throw new Error(t.client.autoStartFailed(logPath));
await new Promise((resolve) => setTimeout(resolve, 250));
}
}
/** Resolves where to connect (see the module doc for the order); may auto-start a server. */
export async function resolveConnection(
opts: { server?: string; autoStart?: boolean },
t: Messages,
): Promise<Connection> {
const root = resolveRoot();
const explicit = opts.server?.trim() || process.env.ADELIE_API_URL?.trim() || "";
if (explicit !== "") {
const url = normalizeServerUrl(explicit, t);
const loopback = isLoopbackUrl(url);
if (!loopback && !process.env.ADELIE_API_TOKEN?.trim()) {
throw new Error(t.client.remoteNeedsToken(url.origin));
}
return { baseUrl: url.origin, root, autoStarted: false, loopback };
}
const lock = await liveServerLock(root);
if (lock !== null) {
return { baseUrl: `http://localhost:${lock.port}`, root, autoStarted: false, loopback: true };
}
if (opts.autoStart === false) throw new Error(t.client.noServer());
const { port, logPath } = await autoStartServer(root, t);
const conn: Connection = {
baseUrl: `http://localhost:${port}`,
root,
autoStarted: true,
loopback: true,
};
process.stderr.write(`${t.client.autoStarted(conn.baseUrl, logPath)}\n`);
return conn;
}
/**
* Error the client raises for non-2xx responses; `code` is the server's error code when the body
* carried one, and `body` the parsed JSON body itself (undefined when it was not JSON), for a
* command that renders the server's own words or reads a field beside the code.
*/
export class ApiError extends Error {
constructor(
readonly status: number,
readonly code: string,
message: string,
readonly body?: unknown,
) {
super(message);
}
/** The server's own message, unwrapped (empty when the body carried none) — for a caller that localizes the code and still needs the specifics. */
get detail(): string {
const message = (this.body as { error?: { message?: unknown } } | null | undefined)?.error
?.message;
return typeof message === "string" ? message : "";
}
}
/**
* Lets go of a response body nobody is going to read. `cancel()` itself rejects whenever the
* stream is already errored — a connection that died mid-body, a probe the readiness timeout
* aborted — and the CLI installs no unhandled-rejection handler, so Node's default ends the
* process for it: a command that only meant to drop a body would die instead of carrying on.
* The server's own drop sites (model-balance, plugin-download, theme-download, proxy-probe)
* all swallow this already; the SSE reader below does the same for its reader.
*/
export function discardBody(res: Response): void {
void res.body?.cancel().catch(() => undefined);
}
export class ServerClient {
private token: string | null;
private tokenSource: TokenSource;
constructor(
readonly conn: Connection,
private readonly t: Messages,
) {
const envToken = process.env.ADELIE_API_TOKEN?.trim();
if (envToken) {
this.token = envToken;
this.tokenSource = "env";
} else if (conn.loopback) {
this.token = readTokenFile(conn.root);
this.tokenSource = this.token !== null ? "file" : "none";
} else {
this.token = null;
this.tokenSource = "none";
}
}
private headers(extra: Record<string, string> = {}): Record<string, string> {
return {
...(this.token !== null ? { authorization: `Bearer ${this.token}` } : {}),
...extra,
};
}
/**
* One JSON request. 401 with a file-sourced token re-reads the file once (the server
* may have restarted and rotated it) and retries; 403 `human_required` retries once as the
* person's stored sign-in (see fetchAuthed); every other non-2xx becomes an ApiError
* carrying the server's code and message.
*/
async request<T>(method: string, apiPath: string, body?: unknown): Promise<T> {
const res = await this.fetchAuthed(apiPath, {
method,
headers: this.headers(body !== undefined ? { "content-type": "application/json" } : {}),
...(body !== undefined ? { body: JSON.stringify(body) } : {}),
});
if (!res.ok) throw await this.toError(res);
if (res.status === 204 || res.headers.get("content-length") === "0") {
discardBody(res);
return undefined as T;
}
const text = await res.text();
return (text === "" ? undefined : JSON.parse(text)) as T;
}
/**
* The authenticated fetch: the one-shot 401 file-token refresh, then the one-shot retry of a
* 403 `human_required` as the person's stored sign-in.
*/
private async fetchAuthed(apiPath: string, init: RequestInit): Promise<Response> {
const res = await this.fetchWithToken(apiPath, init);
return res.status === 403 ? this.retryAsPerson(apiPath, init, res) : res;
}
/** The token's fetch, with the one-shot 401 file-token refresh. */
private async fetchWithToken(apiPath: string, init: RequestInit): Promise<Response> {
const res = await fetch(`${this.conn.baseUrl}${apiPath}`, init);
if (res.status !== 401) return res;
if (this.tokenSource === "env" || !this.conn.loopback) return res;
const fresh = readTokenFile(this.conn.root);
if (fresh === null || fresh === this.token) return res;
discardBody(res);
this.token = fresh;
this.tokenSource = "file";
const headers = { ...(init.headers as Record<string, string>), ...this.headers() };
return fetch(`${this.conn.baseUrl}${apiPath}`, { ...init, headers });
}
/**
* `refused` was a 403. When it is `human_required` and there is a stored sign-in to use (see the
* module doc), sends the same request once more as that sign-in — the session cookie, no
* Bearer, since the server reads a Bearer first — and answers with that. The refusal stands
* when there is no usable sign-in, and when the server does not accept the sign-in either (a
* 401: it expired or was revoked), so the caller still sees `human_required`.
*/
private async retryAsPerson(
apiPath: string,
init: RequestInit,
refused: Response,
): Promise<Response> {
if (!this.conn.loopback) return refused;
const signIn = readStoredSignIn(this.conn.root);
if (signIn === null) return refused;
if ((await errorCodeOf(refused.clone())) !== HUMAN_REQUIRED) return refused;
const headers: Record<string, string> = { cookie: `${SESSION_COOKIE}=${signIn}` };
for (const [name, value] of Object.entries((init.headers ?? {}) as Record<string, string>)) {
if (name.toLowerCase() !== "authorization") headers[name] = value;
}
const retried = await fetch(`${this.conn.baseUrl}${apiPath}`, { ...init, headers });
if (retried.status === 401) {
discardBody(retried);
return refused;
}
discardBody(refused);
return retried;
}
private async toError(res: Response): Promise<ApiError> {
let code = "http_error";
let message = "";
let payload: unknown;
try {
payload = await res.json();
const body = payload as { error?: { code?: string; message?: string } } | null;
if (body?.error?.code) code = body.error.code;
if (body?.error?.message) message = body.error.message;
} catch {
// Non-JSON error body: keep the fallback wording.
}
if (res.status === 401) {
return new ApiError(
401,
"unauthorized",
this.token === null
? this.t.client.noToken(this.conn.baseUrl, apiTokenPath(this.conn.root))
: this.t.client.authFailed(this.conn.baseUrl),
);
}
return new ApiError(
res.status,
code,
this.t.client.httpError(res.status, code, message),
payload,
);
}
/**
* Opens one SSE subscription (fetch with headers — EventSource cannot carry the
* Bearer token) and yields parsed frames. The caller handles reconnects; aborting
* `signal` ends the generator quietly.
*/
async *sse(apiPath: string, opts: { lastEventId?: string; signal?: AbortSignal } = {}) {
const res = await this.fetchAuthed(apiPath, {
headers: this.headers({
accept: "text/event-stream",
...(opts.lastEventId !== undefined ? { "last-event-id": opts.lastEventId } : {}),
}),
...(opts.signal ? { signal: opts.signal } : {}),
});
if (!res.ok || res.body === null) throw await this.toError(res);
yield* parseSseBody(res.body, opts.signal);
}
}
/**
* Minimal SSE parser over a fetch body: `id:` / `event:` / `data:` fields, multi-line
* data joined with \n, blank line dispatches, `:` comment lines (heartbeats) ignored.
* Tolerates \r\n line endings.
*/
export async function* parseSseBody(
body: ReadableStream<Uint8Array>,
signal?: AbortSignal,
): AsyncGenerator<SseFrame> {
const reader = body.getReader();
const decoder = new TextDecoder();
let buffer = "";
let id: string | undefined;
let event: string | undefined;
let data: string[] = [];
const flush = (): SseFrame | null => {
if (data.length === 0 && event === undefined) {
id = undefined;
event = undefined;
return null;
}
const frame: SseFrame = {
...(id !== undefined ? { id } : {}),
...(event !== undefined ? { event } : {}),
data: data.join("\n"),
};
event = undefined;
data = [];
return frame;
};
try {
for (;;) {
if (signal?.aborted) return;
const { done, value } = await reader.read();
if (done) return;
buffer += decoder.decode(value, { stream: true });
for (;;) {
const nl = buffer.indexOf("\n");
if (nl === -1) break;
let line = buffer.slice(0, nl);
buffer = buffer.slice(nl + 1);
if (line.endsWith("\r")) line = line.slice(0, -1);
if (line === "") {
const frame = flush();
if (frame) yield frame;
continue;
}
if (line.startsWith(":")) continue; // heartbeat comment
const colon = line.indexOf(":");
const field = colon === -1 ? line : line.slice(0, colon);
let value2 = colon === -1 ? "" : line.slice(colon + 1);
if (value2.startsWith(" ")) value2 = value2.slice(1);
if (field === "data") data.push(value2);
else if (field === "event") event = value2;
else if (field === "id") id = value2;
// Other fields (retry) are ignored.
}
}
} finally {
try {
await reader.cancel();
} catch {
// The stream is already closed/errored; nothing to release.
}
}
}
// ---------------------------------------------------------------------------
// Session references
// ---------------------------------------------------------------------------
/** The 8-hex tail of a session id — the short form `penguin ls` prints. */
export function shortSessionId(sessionId: string): string {
const m = /-([0-9a-f]{8})$/.exec(sessionId);
return m === null ? sessionId : m[1]!;
}
/** Minimal shape of a session row for reference resolution (matches the server's SessionInfo). */
export interface SessionRef {
sessionId: string;
agentId: string;
}
/**
* Resolves a session argument: a full session id is used as-is; anything else is a
* fragment matched as a substring over the project's sessions (all agents). Exactly one
* match resolves; zero or several are errors — the ambiguous error lists the candidates.
*/
export async function resolveSessionRef(
client: ServerClient,
projectId: string,
ref: string,
t: Messages,
): Promise<string> {
const trimmed = ref.trim();
if (SESSION_ID_RE.test(trimmed)) return trimmed;
const { agents } = await client.request<{ agents: Array<{ agentId: string }> }>(
"GET",
`/api/projects/${encodeURIComponent(projectId)}/agents`,
);
const candidates: string[] = [];
for (const agent of agents) {
const { sessions } = await client.request<{ sessions: SessionRef[] }>(
"GET",
`/api/projects/${encodeURIComponent(projectId)}/agents/${encodeURIComponent(agent.agentId)}/sessions`,
);
for (const s of sessions) {
if (s.sessionId.includes(trimmed)) candidates.push(s.sessionId);
}
}
if (candidates.length === 1) return candidates[0]!;
if (candidates.length === 0) throw new Error(t.client.sessionNotFound(trimmed, projectId));
throw new Error(t.client.sessionAmbiguous(trimmed, candidates));
}
// ---------------------------------------------------------------------------
// Shared option defaults
// ---------------------------------------------------------------------------
/** `--project-id` default chain: flag > ADELIE_PROJECT_ID > default_project. */
export function resolveProjectId(flag: string | undefined): string {
return flag?.trim() || process.env.ADELIE_PROJECT_ID?.trim() || "default_project";
}
/** `--agent-id` default chain: flag > ADELIE_AGENT_ID > default_agent. */
export function resolveAgentId(flag: string | undefined): string {
return flag?.trim() || process.env.ADELIE_AGENT_ID?.trim() || "default_agent";
}