Skip to content

Self-hosted, Self-Improving, Federated Everything App — dev management, agent orchestration, persistent mind, digital twin, second brain, and creative pipeline from a single dashboard over Tailscale to port the user into the OS

8.8 KB
Raw Blame
/**
 * Spawn working-directory resolution for provider runs and agents.
 *
 * Every AI provider run and CoS agent gets a `workspacePath` (the selected
 * app's repoPath) and spawns its CLI/TUI with that as the child's cwd. When the
 * value is missing the spawn falls back to the PortOS repo root — which is a
 * reasonable default, but used to be *silent*: a prompt like "create
 * HelloWorld.md" then wrote into the PortOS checkout while the UI still showed
 * the app as the selected workspace, with nothing anywhere saying which
 * directory had actually been used (issue #3180).
 *
 * This module makes that decision explicit and loud in the two ways that
 * matter: it logs the effective cwd for every spawn, and it rejects a workspace
 * that was requested but does not exist on disk (a typo'd or moved repo path)
 * rather than quietly running somewhere else.
 *
 * Note this can only catch a workspace that *resolved to something wrong*. The
 * other half of #3180 — an app that resolves to no path at all — has to be
 * caught where the app is looked up, because "no path" arrives here
 * indistinguishable from "no app selected". `getAppWorkspace` returns `null`
 * for that case rather than silently substituting the PortOS root.
 *
 * `withSpawnCwdEnv` covers the remaining failure mode: a CLI that resolves its
 * own working directory from the inherited `PWD` env var rather than from the
 * cwd it was actually spawned in (issue #3193).
 */

import { join } from 'path';
import { tmpdir } from 'os';
import { statSync } from 'fs';
import { rm } from 'fs/promises';
import { expandHome } from './fileUtils.js';

/**
 * Creative Director treatment/plan/evaluate tasks are HTTP-PATCH deliverables
 * (`noCodeOutput`) and never asked for a worktree. Spawning them with
 * `cwd = PATHS.root` lets Claude Code / Codex natively discover the PortOS
 * repo's AGENTS.md files — the same dev-convention bloat the API path already
 * skips via `skipClaudeMd`. A per-agent scratch dir with no AGENTS.md in its
 * tree is the provider-agnostic fix (#4650).
 *
 * `useWorktree: true` keeps the worktree: an explicit isolation request still
 * wins. CD production tasks always set `useWorktree: false`.
 */
export function usesCreativeDirectorScratchCwd(task) {
  if (!task?.metadata?.creativeDirector) return false;
  const useWorktree = task.metadata.useWorktree;
  return useWorktree !== true && useWorktree !== 'true';
}

/**
 * Isolated cwd for a CD-marked CLI/TUI run. Lives under the OS temp dir — NOT
 * under the PortOS checkout (`data/cos/agents` is still inside the git tree,
 * so Claude Code / Codex walking parent directories would still find the repo
 * AGENTS.md). `agentId` is required — a missing id would collapse every CD run
 * onto one shared folder.
 */
export function creativeDirectorScratchCwd(agentId) {
  if (typeof agentId !== 'string' || !agentId) {
    throw new Error('creativeDirectorScratchCwd requires a non-empty agentId');
  }
  return join(tmpdir(), 'portos-cd-cwd', agentId);
}

/** Best-effort: missing dirs are a no-op (`force: true`). */
export async function removeCreativeDirectorScratchCwd(agentId) {
  await rm(creativeDirectorScratchCwd(agentId), { recursive: true, force: true });
}

/**
 * Spawn-site cwd for a CoS agent. CD scratch tasks always resolve to the
 * per-agent scratch path (even if the caller still handed `PATHS.root`);
 * everyone else keeps the existing `workspacePath || fallbackRoot` rule.
 */
export function resolveAgentCliCwd({ workspacePath, fallbackRoot, task, agentId } = {}) {
  if (usesCreativeDirectorScratchCwd(task)) return creativeDirectorScratchCwd(agentId);
  return workspacePath && typeof workspacePath === 'string' ? workspacePath : fallbackRoot;
}

/**
 * Resolve the working directory for a spawned run or agent.
 *
 * @param {string|undefined|null} workspacePath - caller-supplied workspace (app repoPath)
 * @param {string} fallbackRoot - directory to use when no workspace was supplied
 * @param {string} [label] - short run/agent identifier used in the log line
 * @param {{ log?: boolean }} [options] - `log: false` when the caller logs the
 *   final directory itself. An agent prep resolves the source repo here and
 *   then may replace it with a worktree; logging the source as "cwd" reads as
 *   if the agent were about to edit the primary checkout.
 * @returns {string} the directory to hand to `spawn`/`pty.spawn` as `cwd`
 * @throws {Error} when `workspacePath` was supplied but is not an existing directory
 */
export function resolveSpawnCwd(workspacePath, fallbackRoot, label = 'run', { log = true } = {}) {
  // "Nothing was supplied" and "something blank was supplied" are different
  // answers and must not collapse. `repoPath` is validated only as
  // `z.string().min(1)`, so an app can hold "   " — that is a MISCONFIGURED
  // workspace, not an absent one. Deciding on the trimmed value would turn it
  // back into the fallback root and silently run in the PortOS checkout: the
  // exact bug this module exists to prevent, reachable through the one input
  // the schema still lets through.
  const supplied = typeof workspacePath === 'string' && workspacePath.length > 0;
  if (!supplied) {
    if (log) console.log(`📂 ${label} cwd: ${fallbackRoot} (no workspace selected)`);
    return fallbackRoot;
  }

  // expandHome so a repoPath saved as `~/Projects/App` resolves instead of
  // hard-failing as "does not exist" — every other user-supplied-path boundary
  // in the repo expands it too.
  const requested = expandHome(workspacePath.trim());
  if (!requested) {
    throw new Error(
      `Workspace path is blank: the Repository Path for this app is only whitespace. `
      + `Set it to the repo folder (Apps → edit → Repository Path) and run again.`
    );
  }

  // Fail loudly instead of silently running in the PortOS checkout. A bad
  // repoPath is a configuration error the user can fix; running the agent
  // somewhere else and reporting success is not recoverable after the fact.
  const stats = statSync(requested, { throwIfNoEntry: false });
  if (!stats) {
    throw new Error(
      `Workspace path does not exist: ${requested}. `
      + `Fix the Repository Path for this app (Apps → edit → Repository Path) and run again.`
    );
  }
  if (!stats.isDirectory()) {
    throw new Error(
      `Workspace path is not a directory: ${requested}. `
      + `Set the app's Repository Path to the repo folder, not a file.`
    );
  }

  if (log) console.log(`📂 ${label} cwd: ${requested}`);
  return requested;
}

// Windows environment-variable names are case-insensitive, so a spread of
// `process.env` can surface this variable as `Pwd`/`pwd`. Adding a separate
// `PWD` key to that object would hand the child two spellings of one variable
// with no defined winner — so every case variant is dropped before the correct
// value is set.
const PWD_KEY_RE = /^pwd$/i;

/**
 * Return a copy of `env` whose `PWD` names the directory the child will
 * actually run in.
 *
 * Passing `cwd` to `spawn()` changes the child's real working directory but
 * does NOT rewrite `PWD` in the inherited environment — that variable is
 * maintained by the shell, so a child spawned from the long-running PortOS
 * server inherits `PWD=<the PortOS checkout>` no matter where it was pointed.
 * Most CLIs never notice, because they read `process.cwd()`. OpenCode does:
 * `opencode run` resolves its project root as `process.env.PWD ?? process.cwd()`
 * (`packages/opencode/src/cli/cmd/run.ts`), so it ran every PortOS agent in the
 * PortOS folder while the spawn logs correctly reported the app's workspace —
 * "create HelloWorld.md" landed in the PortOS checkout, and asking the agent to
 * print its own working directory printed the PortOS path (issue #3193,
 * follow-up to #3180). Codex/Claude/Gemini were unaffected, which is why the
 * bug looked OpenCode-specific.
 *
 * Upstream closed that behavior as won't-fix and documented exporting a correct
 * `PWD` as the supported workaround, so PortOS pins it at every spawn site.
 * This is the right fix generally, not just for OpenCode: a `PWD` that
 * disagrees with the child's actual cwd is wrong for any process that reads it,
 * and pinning it costs nothing for the ones that don't.
 *
 * @param {NodeJS.ProcessEnv|object} env - env the child would otherwise receive
 * @param {string|undefined|null} cwd - the directory being passed to `spawn` as `cwd`
 * @returns {object} a copy of `env` with `PWD` set to `cwd` (unchanged copy when `cwd` is absent)
 */
export function withSpawnCwdEnv(env, cwd) {
  const next = { ...(env || {}) };
  // No cwd means the child inherits the parent's real working directory, so the
  // inherited PWD is already truthful — stripping it would substitute a
  // different lie for the one being fixed.
  if (typeof cwd !== 'string' || !cwd) return next;
  for (const key of Object.keys(next)) if (PWD_KEY_RE.test(key)) delete next[key];
  next.PWD = cwd;
  return next;
}