pix-runtime

Pix's small shared runtime layer. It owns the process-wide config contract: ~/.pi/agent/pix.json as a single, sparse, versioned user config file, plus the lifecycle that keeps it coherent.

It is not an aggregator, renderer, model-data package, or service locator. See DESIGN.md for the full contract.

What it does

• Versioned, sparse pix.json ($version: 1) — defaults resolve in code.
• Typed sections: collapse, pretty, io, compaction, optimizer, gate.
• Atomic writes behind a serialized in-process queue and a short-lived cross-process lock. A failed write leaves the old file intact.
• Immutable, deeply frozen config snapshots with a monotonic revision.
• Typed, path-filtered change events.
• One-time migration of legacy unversioned config and the optimizer.json sidecar.
• The /pix shared-settings command.

Install

pi install npm:@xynogen/pix-runtime

Standalone-installable: importing an accessor lazily creates the singleton even without the extension factory. Installed via pix-core it registers /pix and session hooks once.

Usage

import { config, updateConfig, onConfigChange } from "@xynogen/pix-runtime/config";
import { prettySection } from "@xynogen/pix-runtime/sections";

const icons = config(prettySection).icons;         // synchronous read
await updateConfig(prettySection, { icons: "ascii" });
const off = onConfigChange((c) => render(), { paths: ["pretty.icons"] });

import { ioTimeoutMs, ioTimeoutSignal } from "@xynogen/pix-runtime/io";
const timeoutMs = ioTimeoutMs();                    // shared network timeout
const signal = ioTimeoutSignal(toolSignal);         // timeout + cancellation

Set io.timeoutSec in ~/.pi/agent/pix.json, or change Network → timeout (sec) with /pix. The default is 30 seconds. It applies to Pix network operations, including remote skills, web fetch/search/transcription, MCP requests and connection bootstrap, background model-data refreshes, and update downloads.

Set compaction.triggerPercent in ~/.pi/agent/pix.json, or change Compaction → Trigger (% ctx) with /pix. It is the context-window usage percent (0–100) used to calculate the trigger; the default is 60 and 0 disables the self-trigger (pi decides when to compact). The /pix picker offers 0, 5, 10, 15, 20, 25, 30, 40, 50, 60, 70, 80, 90.

compaction.minimumTokens is the absolute floor for that calculation. The effective threshold is max(contextWindow × triggerPercent, minimumTokens), so a 300K-context model at 10% waits for 100K tokens instead of compacting at 30K. The default floor is 100K and the hard minimum is 25K (values below clamp up); /pix offers 25K, 50K, 100K, 150K, 200K, 300K, 400K, 600K, 800K, and 1M. pix-core consumes both settings.

Collapse policy helpers:

import { shouldCollapse, collapseDelayMs } from "@xynogen/pix-runtime/collapse";

Testing

import { createIsolatedRuntime } from "@xynogen/pix-runtime/testing";

const { runtime, cleanup } = createIsolatedRuntime();
// ... exercise runtime against a temp agent dir ...
cleanup();