@mewbleh/purrx 1.0.8

package/src/auth/login.js

@@ -0,0 +1,199 @@
+import http from "node:http";
+import { URL } from "node:url";
+import {
+  OAUTH_CLIENT_ID,
+  OAUTH_ISSUER,
+  OAUTH_PORT,
+  OAUTH_SCOPE,
+} from "../config.js";
+import { generatePkce, generateState } from "./pkce.js";
+import {
+  buildAuthFromTokens,
+  writeAuth,
+  jwtAuthClaims,
+} from "./tokens.js";
+import { openBrowser } from "../platform.js";
+
+function buildAuthorizeUrl(redirectUri, pkce, state) {
+  const params = new URLSearchParams({
+    response_type: "code",
+    client_id: OAUTH_CLIENT_ID,
+    redirect_uri: redirectUri,
+    scope: OAUTH_SCOPE,
+    code_challenge: pkce.codeChallenge,
+    code_challenge_method: "S256",
+    id_token_add_organizations: "true",
+    codex_cli_simplified_flow: "true",
+    state,
+  });
+  return `${OAUTH_ISSUER}/oauth/authorize?${params.toString()}`;
+}
+
+// Exchange the authorization code for id/access/refresh tokens.
+/**
+ * @returns {Promise<{id_token: string, access_token: string, refresh_token: string}>}
+ */
+async function exchangeCodeForTokens(code, redirectUri, pkce) {
+  const body = new URLSearchParams({
+    grant_type: "authorization_code",
+    code,
+    redirect_uri: redirectUri,
+    client_id: OAUTH_CLIENT_ID,
+    code_verifier: pkce.codeVerifier,
+  });
+  const resp = await fetch(`${OAUTH_ISSUER}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/x-www-form-urlencoded" },
+    body: body.toString(),
+  });
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`Token exchange failed (${resp.status}): ${text}`);
+  }
+  return /** @type {any} */ (await resp.json());
+}
+
+// Token-exchange the id_token for an OpenAI API key (best effort).
+/**
+ * @param {string} idToken
+ * @returns {Promise<string|null>}
+ */
+async function obtainApiKey(idToken) {
+  const body = new URLSearchParams({
+    grant_type: "urn:ietf:params:oauth:grant-type:token-exchange",
+    client_id: OAUTH_CLIENT_ID,
+    requested_token: "openai-api-key",
+    subject_token: idToken,
+    subject_token_type: "urn:ietf:params:oauth:token-type:id_token",
+  });
+  try {
+    const resp = await fetch(`${OAUTH_ISSUER}/oauth/token`, {
+      method: "POST",
+      headers: { "Content-Type": "application/x-www-form-urlencoded" },
+      body: body.toString(),
+    });
+    if (!resp.ok) return null;
+    const json = /** @type {any} */ (await resp.json());
+    return json.access_token || null;
+  } catch {
+    return null;
+  }
+}
+
+// Runs the interactive ChatGPT OAuth login. Resolves once the callback is
+// handled and credentials are persisted.
+export function loginWithChatGPT() {
+  return new Promise((resolve, reject) => {
+    const pkce = generatePkce();
+    const state = generateState();
+    const redirectUri = `http://localhost:${OAUTH_PORT}/auth/callback`;
+    const authUrl = buildAuthorizeUrl(redirectUri, pkce, state);
+
+    const server = http.createServer(async (req, res) => {
+      let parsed;
+      try {
+        parsed = new URL(req.url, `http://localhost:${OAUTH_PORT}`);
+      } catch {
+        res.writeHead(400).end("Bad Request");
+        return;
+      }
+
+      if (parsed.pathname !== "/auth/callback") {
+        res.writeHead(404).end("Not Found");
+        return;
+      }
+
+      const params = parsed.searchParams;
+      const returnedState = params.get("state");
+      const error = params.get("error");
+      const code = params.get("code");
+
+      if (error) {
+        const desc = params.get("error_description") || error;
+        res
+          .writeHead(400, { "Content-Type": "text/html" })
+          .end(`<h1>Sign-in failed</h1><p>${desc}</p>`);
+        cleanup();
+        reject(new Error(`OAuth error: ${desc}`));
+        return;
+      }
+
+      if (returnedState !== state) {
+        res.writeHead(400).end("State mismatch");
+        cleanup();
+        reject(new Error("OAuth state mismatch"));
+        return;
+      }
+
+      if (!code) {
+        res.writeHead(400).end("Missing authorization code");
+        cleanup();
+        reject(new Error("Missing authorization code"));
+        return;
+      }
+
+      try {
+        const tokens = await exchangeCodeForTokens(code, redirectUri, pkce);
+        const apiKey = await obtainApiKey(tokens.id_token);
+        const auth = buildAuthFromTokens({
+          apiKey,
+          idToken: tokens.id_token,
+          accessToken: tokens.access_token,
+          refreshToken: tokens.refresh_token,
+        });
+        const file = writeAuth(auth);
+
+        const claims = jwtAuthClaims(tokens.id_token);
+        const plan = claims["chatgpt_plan_type"] || "unknown";
+
+        res.writeHead(200, { "Content-Type": "text/html" }).end(
+          `<html><body style="font-family:sans-serif;text-align:center;padding-top:80px">
+            <h1>✓ Signed in to purrx</h1>
+            <p>You can close this tab and return to your terminal.</p>
+          </body></html>`
+        );
+        cleanup();
+        resolve({ file, plan });
+      } catch (err) {
+        res
+          .writeHead(500, { "Content-Type": "text/html" })
+          .end(`<h1>Sign-in failed</h1><p>${err.message}</p>`);
+        cleanup();
+        reject(err);
+      }
+    });
+
+    function cleanup() {
+      setTimeout(() => server.close(), 100);
+    }
+
+    server.on("error", (err) => {
+      if (/** @type {NodeJS.ErrnoException} */ (err).code === "EADDRINUSE") {
+        reject(
+          new Error(
+            `Port ${OAUTH_PORT} is already in use. Close any other Codex/purrx login and try again.`
+          )
+        );
+      } else {
+        reject(err);
+      }
+    });
+
+    server.listen(OAUTH_PORT, "127.0.0.1", () => {
+      console.log("\nOpening your browser to sign in with ChatGPT...");
+      console.log("If it doesn't open, paste this URL:\n");
+      console.log(`  ${authUrl}\n`);
+      openBrowser(authUrl);
+    });
+  });
+}
+
+// Stores a bare API key as auth.json.
+export function loginWithApiKey(apiKey) {
+  const auth = {
+    OPENAI_API_KEY: apiKey,
+    tokens: null,
+    last_refresh: new Date().toISOString(),
+  };
+  return writeAuth(auth);
+}

package/src/auth/pkce.js

@@ -0,0 +1,34 @@
+import crypto from "node:crypto";
+
+/**
+ * @param {Buffer} buf
+ * @returns {string}
+ */
+function base64url(buf) {
+  return buf
+    .toString("base64")
+    .replace(/\+/g, "-")
+    .replace(/\//g, "_")
+    .replace(/=+$/, "");
+}
+
+/**
+ * Generate a PKCE code_verifier / code_challenge (S256) pair, matching the
+ * Codex login flow.
+ * @returns {{ codeVerifier: string, codeChallenge: string }}
+ */
+export function generatePkce() {
+  const codeVerifier = base64url(crypto.randomBytes(64));
+  const codeChallenge = base64url(
+    crypto.createHash("sha256").update(codeVerifier).digest()
+  );
+  return { codeVerifier, codeChallenge };
+}
+
+/**
+ * Random opaque state value for CSRF protection.
+ * @returns {string}
+ */
+export function generateState() {
+  return base64url(crypto.randomBytes(32));
+}

package/src/auth/tokens.js

@@ -0,0 +1,186 @@
+import fs from "node:fs";
+import {
+  authFilePath,
+  purrxHome,
+  OAUTH_CLIENT_ID,
+  OAUTH_ISSUER,
+} from "../config.js";
+
+/** @typedef {import("../types.js").AuthDotJson} AuthDotJson */
+/** @typedef {import("../types.js").AuthInfo} AuthInfo */
+
+// ---------------------------------------------------------------------------
+// auth.json read / write
+// ---------------------------------------------------------------------------
+
+/** @returns {AuthDotJson|null} */
+export function readAuth() {
+  const file = authFilePath();
+  try {
+    const raw = fs.readFileSync(file, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * @param {AuthDotJson} auth
+ * @returns {string} the path written to
+ */
+export function writeAuth(auth) {
+  const dir = purrxHome();
+  fs.mkdirSync(dir, { recursive: true });
+  const file = authFilePath();
+  fs.writeFileSync(file, JSON.stringify(auth, null, 2), { mode: 0o600 });
+  try {
+    fs.chmodSync(file, 0o600);
+  } catch {
+    // best effort on platforms without POSIX perms (Windows)
+  }
+  return file;
+}
+
+export function clearAuth() {
+  const file = authFilePath();
+  try {
+    fs.rmSync(file);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// JWT helpers
+// ---------------------------------------------------------------------------
+
+export function decodeJwt(jwt) {
+  try {
+    const parts = jwt.split(".");
+    if (parts.length < 2) return {};
+    const payload = Buffer.from(parts[1], "base64url").toString("utf8");
+    return JSON.parse(payload);
+  } catch {
+    return {};
+  }
+}
+
+// Extracts the OpenAI auth claims object embedded in the id/access token.
+export function jwtAuthClaims(jwt) {
+  const claims = decodeJwt(jwt);
+  return claims["https://api.openai.com/auth"] || {};
+}
+
+// ---------------------------------------------------------------------------
+// Build an AuthDotJson-compatible structure from exchanged tokens
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{apiKey?: string|null, idToken: string, accessToken: string, refreshToken: string}} params
+ * @returns {AuthDotJson}
+ */
+export function buildAuthFromTokens({ apiKey, idToken, accessToken, refreshToken }) {
+  const authClaims = jwtAuthClaims(idToken);
+  const accountId = authClaims["chatgpt_account_id"] || null;
+  return {
+    OPENAI_API_KEY: apiKey || null,
+    tokens: {
+      id_token: idToken,
+      access_token: accessToken,
+      refresh_token: refreshToken,
+      account_id: accountId,
+    },
+    last_refresh: new Date().toISOString(),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Token refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string} refreshToken
+ * @returns {Promise<{access_token?: string, id_token?: string, refresh_token?: string}>}
+ */
+export async function refreshTokens(refreshToken) {
+  const resp = await fetch(`${OAUTH_ISSUER}/oauth/token`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      client_id: OAUTH_CLIENT_ID,
+      grant_type: "refresh_token",
+      refresh_token: refreshToken,
+      scope: "openid profile email",
+    }),
+  });
+  if (!resp.ok) {
+    const text = await resp.text();
+    throw new Error(`Token refresh failed (${resp.status}): ${text}`);
+  }
+  return /** @type {any} */ (await resp.json());
+}
+
+// Returns a valid auth object, refreshing ChatGPT tokens if they are older than
+// ~28 days. Persists any refresh back to disk.
+export async function ensureFreshAuth() {
+  const auth = readAuth();
+  if (!auth) return null;
+
+  // API-key only auth needs no refresh.
+  if (!auth.tokens) return auth;
+
+  const lastRefresh = auth.last_refresh ? new Date(auth.last_refresh) : null;
+  const ageMs = lastRefresh ? Date.now() - lastRefresh.getTime() : Infinity;
+  const TWENTY_EIGHT_DAYS = 28 * 24 * 60 * 60 * 1000;
+
+  if (ageMs < TWENTY_EIGHT_DAYS && auth.tokens.access_token) {
+    return auth;
+  }
+
+  if (!auth.tokens.refresh_token) return auth;
+
+  try {
+    const refreshed = await refreshTokens(auth.tokens.refresh_token);
+    auth.tokens.access_token = refreshed.access_token || auth.tokens.access_token;
+    auth.tokens.id_token = refreshed.id_token || auth.tokens.id_token;
+    if (refreshed.refresh_token) {
+      auth.tokens.refresh_token = refreshed.refresh_token;
+    }
+    auth.last_refresh = new Date().toISOString();
+    writeAuth(auth);
+  } catch (err) {
+    console.error(`Warning: could not refresh tokens: ${err.message}`);
+  }
+  return auth;
+}
+
+// ---------------------------------------------------------------------------
+// Auth selection: how do we talk to the API?
+// ---------------------------------------------------------------------------
+
+// Returns { mode, accessToken, accountId } describing how to authenticate.
+//   mode = "apikey"  -> use OPENAI_API_KEY against api.openai.com
+//   mode = "chatgpt" -> use OAuth access token against the codex backend
+/**
+ * @param {AuthDotJson|null} auth
+ * @returns {AuthInfo|null}
+ */
+export function resolveAuthMode(auth) {
+  // Environment variable always wins for explicit API-key usage.
+  if (process.env.OPENAI_API_KEY) {
+    return { mode: "apikey", apiKey: process.env.OPENAI_API_KEY };
+  }
+  if (!auth) return null;
+  if (auth.tokens?.access_token) {
+    return {
+      mode: "chatgpt",
+      accessToken: auth.tokens.access_token,
+      accountId: auth.tokens.account_id || null,
+    };
+  }
+  if (auth.OPENAI_API_KEY) {
+    return { mode: "apikey", apiKey: auth.OPENAI_API_KEY };
+  }
+  return null;
+}

package/src/config.js

@@ -0,0 +1,57 @@
+import path from "node:path";
+import { dataHome } from "./platform.js";
+
+// OAuth constants taken from the official OpenAI Codex CLI so we can reuse the
+// same ChatGPT-account backend and auth.json files.
+export const OAUTH_CLIENT_ID = "app_EMoamEEZ73f0CkXaXp7hrann";
+export const OAUTH_ISSUER = "https://auth.openai.com";
+export const OAUTH_PORT = 1455;
+export const OAUTH_SCOPE =
+  "openid profile email offline_access api.connectors.read api.connectors.invoke";
+
+// API endpoints.
+export const API_BASE = "https://api.openai.com/v1";
+export const CHATGPT_BASE = "https://chatgpt.com/backend-api/codex";
+
+// Default model. Used as a fallback when discovery is unavailable.
+// gpt-5-codex is the default Codex coding model.
+export const DEFAULT_MODEL = process.env.PURRX_MODEL || "gpt-5-codex";
+
+// Approximate context window (in tokens) used to decide when to auto-compact
+// the conversation history. gpt-5 family models have large windows; we keep a
+// conservative default and trigger compaction well before the hard limit.
+// Override with PURRX_CONTEXT_LIMIT.
+export const CONTEXT_LIMIT = Number(process.env.PURRX_CONTEXT_LIMIT) || 256_000;
+
+// When estimated/used tokens exceed this fraction of CONTEXT_LIMIT, compact.
+export const COMPACT_THRESHOLD =
+  Number(process.env.PURRX_COMPACT_THRESHOLD) || 0.8;
+
+// Where we store credentials and sessions. Honours PURRX_HOME / CODEX_HOME and
+// otherwise uses an OS-appropriate location (see platform.dataHome).
+export function purrxHome() {
+  return dataHome();
+}
+
+export function authFilePath() {
+  return path.join(purrxHome(), "auth.json");
+}
+
+export function sessionsDir() {
+  return path.join(purrxHome(), "sessions");
+}
+
+export function configFilePath() {
+  return path.join(purrxHome(), "config.json");
+}
+
+// Directory of persistent memory files (*.md) injected into every session.
+export function memoriesDir() {
+  return path.join(purrxHome(), "memories.d");
+}
+
+// Global skills directory. Each skill is a folder containing SKILL.md, or a
+// bare <name>.md file.
+export function skillsDir() {
+  return path.join(purrxHome(), "skills");
+}

package/src/core/agent.js

@@ -0,0 +1,197 @@
+import { streamResponse } from "../api/client.js";
+import { detectPlatform } from "../platform.js";
+import { createSpinner, c, sym, randomWorkingPhrase } from "../ui/theme.js";
+import { renderMarkdown } from "../ui/render.js";
+import { buildContextBlock } from "./context.js";
+import { maybeCompact } from "./compact.js";
+
+function systemInstructions(cwd, registry) {
+  const platform = detectPlatform();
+  const mcpNote =
+    registry && registry.mcpServerCount() > 0
+      ? `\n- You have access to MCP tools (prefixed mcp__). Use them when relevant.`
+      : "";
+  const base = `You are purrx, a lightweight AI coding agent running in the user's terminal.
+You help with software engineering tasks: reading and writing code, running commands, searching, and explaining things.
+
+Environment:
+- Operating system: ${platform}
+- Working directory: ${cwd}
+
+Guidelines:
+- Use the provided tools to inspect and modify the project rather than guessing.
+- Read files before editing them. Prefer edit_file for surgical changes.
+- Use search_files and find_files to explore unfamiliar code.
+- Keep responses concise. Show your work through tool calls.
+- Use shell commands appropriate for the ${platform} platform.
+- When running commands, prefer non-destructive operations and explain risky ones.
+- Use web_search when you need current information beyond your training data.
+- When the user shares a durable preference or project convention, save it with the remember tool.
+- Before a specialized task, check list_skills and load the relevant one with use_skill.${mcpNote}`;
+
+  const context = buildContextBlock(cwd);
+  return context ? `${base}\n\n${context}` : base;
+}
+
+// Runs a single user turn to completion, looping over tool calls until the
+// model produces a final answer.
+/**
+ * @param {Object} opts
+ * @param {import("../types.js").AuthInfo} opts.authInfo
+ * @param {import("../types.js").HistoryItem[]} opts.history running history (mutated)
+ * @param {string} opts.userMessage
+ * @param {string} opts.cwd
+ * @param {string} opts.model
+ * @param {import("../tools/registry.js").ToolRegistry} opts.registry
+ * @param {{requestApproval: (name: string, label: string) => Promise<string>}} [opts.approval]
+ * @param {() => void} [opts.onChange]
+ * @returns {Promise<import("../types.js").HistoryItem[]>}
+ */
+export async function runTurn({
+  authInfo,
+  history,
+  userMessage,
+  cwd,
+  model,
+  registry,
+  approval,
+  onChange,
+}) {
+  history.push({
+    type: "message",
+    role: "user",
+    content: [{ type: "input_text", text: userMessage }],
+  });
+  if (onChange) onChange();
+
+  const tools = registry ? registry.definitions() : [];
+  const spinner = createSpinner(randomWorkingPhrase());
+  let lastUsedTokens = 0;
+
+  while (true) {
+    const toolCalls = [];
+    let buffered = "";
+
+    // Auto-compact before sending if we're near the context limit. This keeps
+    // each request within budget and preserves recent turns + a summary.
+    await maybeCompact({
+      authInfo,
+      history,
+      model,
+      usedTokens: lastUsedTokens,
+      onInfo: (msg) => console.log(c.dim(`  ${sym.bullet} ${msg}`)),
+    });
+
+    spinner.start();
+
+    const finalResponse = await streamResponse(
+      {
+        authInfo,
+        model,
+        input: history,
+        tools,
+        instructions: systemInstructions(cwd, registry),
+      },
+      {
+        onText: (delta) => {
+          buffered += delta;
+        },
+      }
+    );
+
+    spinner.stop();
+
+    if (!finalResponse) {
+      throw new Error("No response received from the model.");
+    }
+
+    // Track real token usage when the API reports it.
+    const used = finalResponse.usage?.total_tokens;
+    if (typeof used === "number" && used > 0) lastUsedTokens = used;
+
+    // Render the assistant's prose as styled Markdown once the turn settles.
+    if (buffered.trim()) {
+      process.stdout.write(renderMarkdown(buffered) + "\n");
+    }
+
+    const output = finalResponse.output || [];
+    for (const item of output) {
+      history.push(item);
+      if (item.type === "function_call") {
+        toolCalls.push(item);
+      }
+    }
+    if (onChange) onChange();
+
+    if (toolCalls.length === 0) {
+      return history;
+    }
+
+    for (const call of toolCalls) {
+      let args = {};
+      try {
+        args = call.arguments ? JSON.parse(call.arguments) : {};
+      } catch {
+        args = {};
+      }
+
+      const label = describeCall(call.name, args);
+
+      let decision = "approve";
+      if (approval) {
+        decision = await approval.requestApproval(call.name, label);
+      }
+
+      let result;
+      if (decision === "reject") {
+        console.log(`${sym.fail} ${c.dim("skipped:")} ${label}`);
+        result = "The user declined to run this action.";
+      } else {
+        console.log(`${sym.tool} ${c.dim(label)}`);
+        result = await registry.execute(call.name, args, cwd);
+      }
+
+      history.push({
+        type: "function_call_output",
+        call_id: call.call_id,
+        output: typeof result === "string" ? result : JSON.stringify(result),
+      });
+      if (onChange) onChange();
+    }
+  }
+}
+
+function describeCall(name, args) {
+  switch (name) {
+    case "read_file":
+      return `read ${args.path}`;
+    case "write_file":
+      return `write ${args.path}`;
+    case "edit_file":
+      return `edit ${args.path}`;
+    case "list_directory":
+      return `list ${args.path || "."}`;
+    case "search_files":
+      return `search /${args.pattern}/${args.glob ? ` in ${args.glob}` : ""}`;
+    case "find_files":
+      return `find ${args.glob}`;
+    case "delete_file":
+      return `delete ${args.path}`;
+    case "run_command":
+      return `run: ${args.command}`;
+    case "fetch_url":
+      return `fetch ${args.url}`;
+    case "remember":
+      return `remember: ${(args.text || "").slice(0, 50)}`;
+    case "use_skill":
+      return `use skill ${args.name}`;
+    case "list_skills":
+      return `list skills`;
+    default:
+      if (name.startsWith("mcp__")) {
+        const [, server, tool] = name.split("__");
+        return `mcp ${server}/${tool}`;
+      }
+      return name;
+  }
+}