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

20.0 KB
Raw Blame
/**
 * Child-environment composition for every AI-CLI spawn.
 *
 * Ten sites independently rebuilt the same env layering, and three separate
 * fixes each paid an N-file sweep to keep them in step: the OpenCode
 * declared-models map (#2190/#2243), the `CLAUDECODE` strip, and the `PWD` pin
 * (#3193). Every time, the guard against missing a site was "a reviewer noticed"
 * or a source-grep test — and one of those sweeps did miss a site (see the
 * comment at `services/agentLifecycle.js#spawnViaRunner`). This module owns the
 * composition so the next env-level concern is a one-file change (#3194).
 *
 * Two entry points, because the sites split into two shapes:
 *
 *   - `buildCliChildEnv` — a COMPLETE child env, handed straight to `spawn`.
 *   - `composeProviderEnv` — just the ordered provider layers, for the sites
 *     that produce a DELTA someone else bases and spawns (the CoS runner
 *     payload, a shell session's env overlay).
 *
 * The layer ORDER is the load-bearing part, and the sites do not all layer the
 * same way — flattening them into one order would silently change which value
 * wins:
 *
 *   - the agent spawners put `forgeTokenEnv`/`claudeSettingsEnv` BEFORE
 *     `provider.envVars`, so an explicit provider `GH_TOKEN` still overrides the
 *     repo-owner-pinned one;
 *   - the PTY runners put `TERM`/`COLORTERM` AFTER everything, so the terminal
 *     is always truecolor regardless of provider config.
 *
 * Hence two distinct slots — `before` (lower precedence than the provider) and
 * `extra` (higher) — rather than one. `cliChildEnv.test.js` asserts the composed
 * order for each call site, and fails when a new site hand-rolls it instead.
 *
 * Deliberately NOT in scope: a `spawnAiCli({ command, args, cwd, env })` wrapper
 * that would also own cwd resolution and the Windows `.cmd` shim. The spawn
 * shapes differ too much (child_process vs node-pty vs an HTTP hand-off to the
 * CoS runner, stdio variants, kill-tree wiring) to fold in the same change.
 * `lib/aiToolkit/runner.js` is also out of scope: it is vendored and must not
 * import out to other PortOS modules (see `lib/aiToolkit/AGENTS.md`), and its
 * spawn is dormant under PortOS's `setCliRunner` override, so it keeps its
 * inline copy.
 */

import { withSpawnCwdEnv } from './spawnCwd.js';
import { buildOpencodeEnvVars } from './opencodeConfig.js';
import {
  localRuntimeNamespace,
  isClaudeCommand,
  parseOpencodeConfigContent,
  opencodeConfigIsLocalOnly,
} from './providerModels.js';
import { isLocalInstanceEndpoint } from './localEndpoint.js';
import { agentGuardEnv } from './agentGuard/index.js';
import { buildSafeCliBaseEnv } from './processEnv.js';
import { isPublicReviewNoToolProfile, isPublicReviewRestrictedProfile } from './agentExecutionProfiles.js';

// Claude Code defaults to 32K output tokens. Thinking-capable local models can
// legitimately spend more than that before returning their final tool call;
// when they do, Claude Code paints a terminal API Error and waits forever at an
// empty composer. Cloud Claude models own their own output budgets, so widen the
// ceiling only for a Claude harness pointed at a LOCAL daemon. A value in
// provider.envVars still wins below.
const CLAUDE_LOCAL_MAX_OUTPUT_TOKENS = '65536';

// A local daemon sends NOTHING — not even response headers — until prefill
// completes (Ollama returns headers and `message_start` together with the first
// token; a 60KB prompt measured 122s of pure silence). A public-review Stage 3
// prompt runs to tens of thousands of tokens, which a model server on this box
// chews through in minutes, not seconds, so the request sits in Claude Code's
// first-byte path for the whole prefill. That path has FOUR independent
// ceilings in Claude Code v2.1.260 (a Bun-compiled binary), each measured
// against a fake stalled `/v1/messages` on loopback (2026-09-04):
//
//   • the Bun `fetch` timeout — ~360s, `API Error: The operation timed out.`
//     Claude Code passes `timeout: false` to fetch only when
//     `API_FORCE_IDLE_TIMEOUT` is explicitly `0`; with it unset or `1` a silent
//     request is re-sent every 361s regardless of every other knob. THIS is the
//     one that froze Stage 3 at `API error · Retrying in 0s · attempt 1/10` on
//     2026-09-03 and 09-04 (agent-e057cca7; the daemon logged
//     `500 | 6m0s | POST /v1/messages` + `srv stop: cancel task` per attempt),
//     which #6117's `API_TIMEOUT_MS` raise alone could not touch.
//   • the first-byte window — `API_TIMEOUT_MS` minus a second (10min default).
//   • the byte-stream idle watchdog, once bytes flow — 180s via a remote flag
//     (300s without it), `API Error: stream idle: no bytes for 180000ms`;
//     `CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS`, clamped to 30 minutes.
//   • the stream idle timeout — 300s; `CLAUDE_STREAM_IDLE_TIMEOUT_MS`, floor
//     300s, likewise clamped to 30 minutes.
//
// All four are widened for a Claude harness pointed at a LOCAL daemon — the
// idle knobs at Claude Code's own 30-minute ceiling, the first-byte window at
// an hour. A request that never answers still ends: `createRetryStallGate`
// (tuiHandshake.js) fails a TUI over once its retry ladder outlives the window,
// and the run's own supervision reaps a silent child. Cloud Claude keeps every
// stock value.
const CLAUDE_LOCAL_API_TIMEOUT_MS = '3600000';
const CLAUDE_LOCAL_FORCE_IDLE_TIMEOUT = '0';
const CLAUDE_LOCAL_STREAM_IDLE_TIMEOUT_MS = '1800000';

/**
 * True for a Claude Code harness talking to a local OpenAI/Anthropic-compatible
 * daemon — `claude-ollama` and `claude-sglang` today, plus any renamed or
 * hand-built provider carrying one of the local-backend markers.
 *
 * Keyed on the marker set rather than `ollamaBacked` alone: SGLang serves an
 * Anthropic-compatible `/v1/messages` endpoint, so a `claude` binary drives it
 * exactly the way it drives Ollama, and the 32K-output wedge above is a
 * property of "local thinking-capable model behind the Claude binary", not of
 * Ollama specifically. Hosted gateways (`providerGateways.js`) are excluded —
 * their upstream models own their own budgets, the same carve-out
 * `localRuntimeKind` makes.
 */
function isLocalBackedClaude(provider) {
  return !!localRuntimeNamespace(provider) && isClaudeCommand(provider?.command);
}

/**
 * Every knob `claudeLocalEnvDefaults` composes for a local-backed Claude
 * harness.
 *
 * Named once because the two public-review allowlists below have to let all of
 * them through, and an allowlist that carries the wrapper's ENDPOINT but not its
 * TUNING is the worst of both: the stage reaches the local daemon and then runs
 * it on Claude Code's cloud-shaped ceilings. That is how Stage 3 — the stage
 * carrying the review envelope — sat behind a 6-minute fetch timeout its
 * prefill could never meet. Keep in lockstep with `claudeLocalEnvDefaults`;
 * `cliChildEnv.test.js` fails when a knob it emits is missing from either list.
 */
const CLAUDE_LOCAL_TUNING_ENV_KEYS = [
  'CLAUDE_CODE_MAX_OUTPUT_TOKENS', 'API_TIMEOUT_MS', 'API_FORCE_IDLE_TIMEOUT',
  'CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS', 'CLAUDE_STREAM_IDLE_TIMEOUT_MS', 'MAX_THINKING_TOKENS',
];

function claudeLocalEnvDefaults(provider) {
  if (!isLocalBackedClaude(provider)) return {};
  return {
    CLAUDE_CODE_MAX_OUTPUT_TOKENS: CLAUDE_LOCAL_MAX_OUTPUT_TOKENS,
    API_TIMEOUT_MS: CLAUDE_LOCAL_API_TIMEOUT_MS,
    API_FORCE_IDLE_TIMEOUT: CLAUDE_LOCAL_FORCE_IDLE_TIMEOUT,
    CLAUDE_BYTE_STREAM_IDLE_TIMEOUT_MS: CLAUDE_LOCAL_STREAM_IDLE_TIMEOUT_MS,
    CLAUDE_STREAM_IDLE_TIMEOUT_MS: CLAUDE_LOCAL_STREAM_IDLE_TIMEOUT_MS,
    // Claude Code omits the Anthropic-compatible `thinking` field when this is
    // zero, which Ollama maps to Qwen's non-thinking mode. Do not set a value
    // when enabled: Claude retains its normal adaptive budget.
    //
    // Ollama-only on purpose. Every other local backend takes its thinking
    // switch as `chat_template_kwargs.enable_thinking`, which the Anthropic
    // wire cannot carry — on SGLang an omitted `thinking` field falls through
    // to Qwen3.8's chat-template default, which is thinking ON. Emitting the
    // var there would look like an off switch while changing nothing, so the
    // provider card does not offer the toggle for those records either (see
    // `generationControlsFor` in client/src/utils/providerModels.js).
    ...(provider.ollamaBacked === true && provider.thinking === false
      ? { MAX_THINKING_TOKENS: '0' }
      : {}),
  };
}

/**
 * The ordered provider env layers, without a base env, PWD pin, or strip.
 *
 * Use this for a site that builds a DELTA — an overlay another layer bases and
 * spawns (`spawnAgentViaRunner`'s `envVars` payload, `createShellSession`'s
 * `env`). Sites that spawn directly want `buildCliChildEnv` instead.
 *
 * @param {object} options
 * @param {object|null} [options.before] - layered first, so `provider.envVars`
 *   overrides it (forgeTokenEnv, claudeSettingsEnv).
 * @param {{command?:string, envVars?:object, models?:string[], defaultModel?:string|null, ollamaBacked?:boolean, lmstudioBacked?:boolean, mtplxBacked?:boolean, llamaBacked?:boolean, vllmBacked?:boolean, sglangBacked?:boolean, gatewayBacked?:string, orcarouterBacked?:boolean, thinking?:boolean}|null} [options.provider]
 * @param {string|null} [options.model] - the model being run this invocation,
 *   unioned into the OpenCode declared-models map. Omit when the site has no
 *   per-call model — `provider.defaultModel` is always declared regardless.
 * @param {object|null} [options.extra] - layered last, so it overrides every
 *   other layer including `provider.envVars` (TERM/COLORTERM for a PTY).
 * @param {string|null} [options.safetyProfile] - a public-review execution
 *   profile, which hardens the OpenCode config (see `buildOpencodeEnvVars`).
 * @returns {object} a fresh object holding only these layers
 */
export function composeProviderEnv({ before = null, provider = null, model = null, extra = null, safetyProfile = null } = {}) {
  // `authOnly` marks an identity-only view of a provider — `cliProviderAuthDescriptor`'s
  // `{ id, command, <local marker> }`, with no `envVars`, `models`, `defaultModel`,
  // or `thinking`. It exists so the CoS runner can keep that provider's ambient
  // auth allowlist (`buildSafeCliBaseEnv`, which still receives it); it is NOT a
  // record to generate env from. Every generator below sits ABOVE `before` in
  // layer order, so running one on a partial view overwrites the complete value
  // PortOS already composed and POSTed. That is how a runner-owned OpenCode
  // agent lost its declared-models map: rebuilt empty from the descriptor,
  // `--model ollama/<id>` stopped resolving, and OpenCode silently fell back to
  // the first model in its own catalog (a hosted OpenCode Zen model) instead of
  // the local model the run was dispatched with.
  if (provider?.authOnly) return { ...(before || {}), ...(extra || {}) };
  return {
    ...(before || {}),
    ...claudeLocalEnvDefaults(provider),
    ...(provider?.envVars || {}),
    // Rebuilds OPENCODE_CONFIG_CONTENT with a declared models map for OpenCode
    // local providers (an empty object for everyone else) so the injected
    // namespaced `--model` isn't rejected as "not valid" — see #2190. It lands
    // after provider.envVars to override the provider's STATIC
    // OPENCODE_CONFIG_CONTENT, which it was built from. `safetyProfile` also
    // reaches it because OpenCode's tool posture lives in that config — see
    // `hardenOpencodeConfigForNoTool`.
    ...buildOpencodeEnvVars(provider, model, { safetyProfile }),
    ...(extra || {}),
  };
}

// Public contributor content is run through a no-tools local harness — a Claude
// or an OpenCode wrapper pointed at a loopback daemon.
// Keep only runtime essentials plus the local model endpoint;
// in particular, never pass forge, cloud, SSH, auth, or arbitrary provider env
// vars into the child. This is a second boundary in addition to the CLI argv.
const PUBLIC_REVIEW_ENV_KEYS = new Set([
  'PATH', 'Path', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'PWD', 'TMPDIR', 'TMP', 'TEMP',
  'LANG', 'LANGUAGE', 'TERM', 'COLORTERM', 'TZ', 'NODE', 'NODE_ENV', 'NODE_PATH',
  'NVM_DIR', 'NVM_BIN', 'XDG_CONFIG_HOME', 'XDG_CACHE_HOME', 'XDG_DATA_HOME',
  'SystemRoot', 'SystemDrive', 'ComSpec', 'PATHEXT', 'USERPROFILE', 'APPDATA',
  'LOCALAPPDATA', 'ProgramData', 'ProgramFiles', 'HOMEDRIVE', 'HOMEPATH',
  'ANTHROPIC_BASE_URL', 'ANTHROPIC_SMALL_FAST_MODEL',
  ...CLAUDE_LOCAL_TUNING_ENV_KEYS,
]);

// A Claude CLI pointed at a LOCAL Anthropic-compatible runtime (the Ollama and
// SGLang wrappers) authenticates with a placeholder token that means nothing
// outside that loopback endpoint, and its lean argv passes `--bare`, which
// disables the keychain — so without the token the CLI exits "Not logged in"
// before reading the prompt. Keep the credential only for a loopback base URL;
// against any other host it is a real cloud credential and stays stripped.
// `isLocalInstanceEndpoint` (localEndpoint.js) is the tree-wide answer to "is
// this endpoint on the machine PortOS runs on?" — the same predicate
// `localRuntimeForProvider` uses to decide a provider HAS a local daemon.
// Reused here rather than re-typed so a credential boundary cannot classify a
// host differently from the runtime resolver; it also counts the bind-all
// addresses (`0.0.0.0`, `::`) as local, which they are.
const LOCAL_ANTHROPIC_CREDENTIAL_KEYS = ['ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_API_KEY'];

function localAnthropicCredentialEnv(env) {
  if (!isLocalInstanceEndpoint(env?.ANTHROPIC_BASE_URL)) return {};
  return Object.fromEntries(LOCAL_ANTHROPIC_CREDENTIAL_KEYS
    .filter((key) => env[key] != null)
    .map((key) => [key, env[key]]));
}

/**
 * An OpenCode run carries its whole configuration — provider endpoint, declared
 * models, and (under a `no-tool` profile) its entire tool posture — in
 * `OPENCODE_CONFIG_CONTENT`, so stripping it does not harden the child, it just
 * points it at the user's own `~/.config/opencode` instead. Keep it, on the same
 * terms as the local Anthropic credential above: only when every endpoint it
 * declares is loopback. A config naming a hosted gateway carries that gateway's
 * API key, which is a real cloud credential and stays stripped — leaving an
 * OpenCode wrapper front-ending a gateway ineligible for these stages, which is
 * why `providerVendors.js` scopes the OpenCode recipe to local namespaces.
 */
function opencodeLocalConfigEnv(env) {
  const raw = env?.OPENCODE_CONFIG_CONTENT;
  // `requireDeclaration` marks this as the provenance-checking caller: a value
  // declaring no endpoint is not a config PortOS built for an eligible provider,
  // so it is dropped with every other inherited env var.
  return opencodeConfigIsLocalOnly(parseOpencodeConfigContent(raw), { requireDeclaration: true })
    ? { OPENCODE_CONFIG_CONTENT: raw }
    : {};
}

function allowlistEnv(env, keys) {
  return {
    ...Object.fromEntries(Object.entries(env || {}).filter(([key, value]) => (
      value != null && (keys.has(key) || key.startsWith('LC_'))
    ))),
    ...localAnthropicCredentialEnv(env),
    ...opencodeLocalConfigEnv(env),
  };
}

// Only explicit bootstrap output may supply these credentials. Never overlay
// arbitrary output: PATH, NODE_OPTIONS, config files and tool settings could
// replace the enforced recipe even though its argv remained unchanged.
const BOOTSTRAP_REVIEW_AUTH_KEYS = new Set([
  'ANTHROPIC_API_KEY', 'ANTHROPIC_AUTH_TOKEN', 'ANTHROPIC_BASE_URL',
  'OPENAI_API_KEY', 'OPENAI_BASE_URL', 'OPENAI_API_BASE',
  'GEMINI_API_KEY', 'GOOGLE_API_KEY', 'GOOGLE_GENAI_API_KEY',
  'XAI_API_KEY', 'GROK_API_KEY', 'KIMI_API_KEY', 'MOONSHOT_API_KEY', 'CURSOR_API_KEY',
]);

export function buildPublicReviewCliEnv(env = {}) {
  return allowlistEnv(env, PUBLIC_REVIEW_ENV_KEYS);
}

// The actions stage is allowed to use its vendor's own workspace sandbox for
// repository inspection and tests, but it must never inherit forge credentials, SSH
// configuration, cloud-provider keys, or arbitrary provider env vars. This is
// deliberately a second strict allowlist rather than a blocklist: a new secret
// added to the server or provider environment must not silently become visible
// to a contributor-controlled review. The deterministic output hook owns every
// forge mutation after the model exits.
const PUBLIC_REVIEW_ACTIONS_ENV_KEYS = new Set([
  'PATH', 'Path', 'HOME', 'USER', 'LOGNAME', 'SHELL', 'PWD', 'TMPDIR', 'TMP', 'TEMP',
  'LANG', 'LANGUAGE', 'TERM', 'COLORTERM', 'TZ', 'NODE', 'NODE_ENV', 'NODE_PATH',
  'NVM_DIR', 'NVM_BIN',
  'SystemRoot', 'SystemDrive', 'ComSpec', 'PATHEXT', 'USERPROFILE', 'APPDATA',
  'LOCALAPPDATA', 'ProgramData', 'ProgramFiles', 'HOMEDRIVE', 'HOMEPATH',
  // The local Claude wrappers are eligible for this stage too; without the
  // endpoint they would talk to the cloud (or, with `--bare`, to nothing).
  'ANTHROPIC_BASE_URL', 'ANTHROPIC_SMALL_FAST_MODEL',
  // ...and the tuning composed for that wrapper, for the reason spelled out on
  // the constant. These are numeric harness knobs carrying no credential, so
  // keeping them widens no boundary this list exists to hold.
  ...CLAUDE_LOCAL_TUNING_ENV_KEYS,
]);

export function buildPublicReviewActionsCliEnv(env = {}) {
  return allowlistEnv(env, PUBLIC_REVIEW_ACTIONS_ENV_KEYS);
}

/**
 * Compose the complete environment an AI-CLI child process is spawned with.
 *
 * Layering, lowest precedence first: `baseEnv` → the `composeProviderEnv` layers
 * → then `PWD` pinned to `cwd`, `CLAUDECODE` stripped, and — only when `guard`
 * is true — the pm2 guard shim prepended to the final `PATH`.
 *
 * @param {object} options
 * @param {NodeJS.ProcessEnv|object} [options.baseEnv=process.env] - env to
 *   start from. It is filtered through `buildSafeCliBaseEnv`; every later
 *   explicit layer still overlays it.
 * @param {object|null} [options.before] - see `composeProviderEnv`.
 * @param {object|null} [options.provider] - see `composeProviderEnv`.
 * @param {string|null} [options.model] - see `composeProviderEnv`.
 * @param {string|undefined|null} options.cwd - the directory being handed to
 *   `spawn`/`pty.spawn`; `PWD` is pinned to it (see `withSpawnCwdEnv`, #3193).
 *   Pass it whenever the spawn names a cwd — omitting it silently reopens #3193,
 *   which is why `spawnCwd.test.js` only counts a call carrying `cwd` as a pin.
 * @param {object|null} [options.extra] - see `composeProviderEnv`.
 * @param {object|null} [options.bootstrapEnv] - Explicit credential-command output; only recognized auth keys pass, in ordinary runs or an opted-in no-tool review.
 * @param {boolean} [options.guard=false] - prepend the pm2 guard shim onto the
 *   final `PATH` so an unrestricted agent can't `pm2 kill` the shared daemon.
 *   Only the agent-spawning sites opt in; the Run Prompt / fire-and-collect
 *   paths keep today's unguarded behavior.
 * @returns {object} a fresh env object safe to hand straight to `spawn`
 */
export function buildCliChildEnv({
  baseEnv = process.env,
  before = null,
  provider = null,
  model = null,
  cwd,
  extra = null,
  guard = false,
  bootstrapEnv = null,
  safetyProfile = null,
} = {}) {
  const composed = withSpawnCwdEnv(
    { ...buildSafeCliBaseEnv(baseEnv, provider), ...composeProviderEnv({ before, provider, model, extra, safetyProfile }) },
    cwd,
  );

  const env = isPublicReviewNoToolProfile(safetyProfile)
    ? buildPublicReviewCliEnv(composed)
    : isPublicReviewRestrictedProfile(safetyProfile)
      ? buildPublicReviewActionsCliEnv(composed)
      : composed;

  if ((!safetyProfile || isPublicReviewNoToolProfile(safetyProfile)) && provider?.credentialBootstrap?.envCommand) {
    Object.assign(env, Object.fromEntries(Object.entries(bootstrapEnv || {})
      .filter(([key, value]) => BOOTSTRAP_REVIEW_AUTH_KEYS.has(key) && typeof value === 'string')));
  }

  // CLAUDECODE is set when PortOS itself runs inside Claude Code; passing it
  // through would make a spawned Claude CLI think it's nested in that session.
  delete env.CLAUDECODE;

  // Must be applied to the FINAL PATH (after every override above), or a
  // provider-configured PATH would drop the shim back off the front.
  if (guard) Object.assign(env, agentGuardEnv(env));

  return env;
}