feat: Offline mode for Pipelex Gateway setup and dry-run

[lchoquel]

Summary

• Adds a schema-versioned on-disk cache at ~/.pipelex/cache/remote_config.json that Pipelex Gateway falls back to when the remote config service is unreachable. Setup, validation, and pipelex-agent run bundle --dry-run complete normally offline; only the actual inference call still needs the network at runtime. The cache is primed on every successful fetch and at pipelex init while online. When the gateway is disabled (BYOK), no remote fetch is attempted at all.
• Adds RemoteConfigStaleWarning (UserWarning) surfaced on the agent-CLI JSON envelope as warnings: [{"type": "RemoteConfigStale", ...}]; suppresses telemetry (no-op) on stale cache; refuses cache for doc/fixture generators via a new require_fresh=True flag.
• Adds two user-facing exceptions: RemoteConfigUnavailableError (offline + cold cache, with two-path remediation) and GatewayUnknownModelError (source-aware messaging when a deck references a gateway handle absent from the fresh-or-cached specs). Both wired through the Rich CLI (error_handlers.py) and the agent CLI (AGENT_ERROR_HINTS / AGENT_ERROR_DOMAINS).
• RemoteConfigFetcher.fetch_remote_config() now returns a RemoteConfigResult(config, source, cached_at); ModelManager.setup() and BackendLibrary._load_gateway_model_specs() accept a gateway_config_source: RemoteConfigSource | None parameter so the membership check can branch its error message on FRESH vs CACHED. GatewayConfig stays extra="forbid" and source-free — provenance is plumbed alongside.
• Adds PIPELEX_REMOTE_CONFIG_URL env var to override the default URL (useful for staging/testing).

See TODOS.md for the full phased implementation plan (Phases 0–7) and the per-checkpoint status blocks with rationale, decisions, and verification notes.

Related

• Unblocks the codex-sandbox handoff scenario described in mthds-plugins/wip/codex-sandbox-escalation.md — --dry-run no longer requires escalation once Pipelex has been initialised online once.

Deferred follow-ups

Tracked at the bottom of TODOS.md:

1. pipelex doctor cache reporting (presence, age, missing-cache hint).
2. Codex Cloud cache-first short-circuit (today returns a dummy unconditionally).
3. Cross-repo update to mthds-plugins/wip/codex-sandbox-escalation.md.
4. Cache TTL revisit (currently uncapped).
5. Schema-version migration runbook.
6. pipelex-agent run bundle --output-dir <path> flag for read-only mounted bundles.
7. Pin GatewayUnknownModelError end-to-end via a deck override that points a preset at a missing handle.

Test plan

• make agent-check — clean (ruff fix-imports, ruff format, plxt fmt, ruff lint, plxt lint, pyright, mypy).
• make agent-test — full suite green.
• Manual reproduction of the behaviour matrix:
  • BYOK offline → success (E2E test_byok_offline_succeeds).
  • Gateway online, no cache → success, cache written (integration + cache-priming tests).
  • Gateway offline, cache present → success with stale warning (E2E test_gateway_known_with_cache_succeeds_offline).
  • Gateway offline, no cache → clear RemoteConfigUnavailableError (E2E test_gateway_no_cache_no_network_fails_with_unavailable).
  • Bundle references unknown gateway model → clear GatewayUnknownModelError (integration test_gateway_unknown_model.py + E2E).
  • pipelex-dev update-gateway-models offline → clear refusal, no stale docs written (manual via PIPELEX_REMOTE_CONFIG_URL=http://127.0.0.1:1/..., pinned in test_require_fresh_refuses_cache).

Documentation

Docs updated in this branch:

• docs/tools/cli/agent-cli.md — added the warnings array to the agent CLI JSON success contract. The branch introduces this top-level envelope field (warnings: [{"type": "RemoteConfigStale", ...}]) but the machine-facing output contract didn't document it. Added a JSON example and noted that RemoteConfigStale is emitted on offline cache fallback.
• docs/tools/cli/init.md — added an "Offline cache priming" note: pipelex init now primes ~/.pipelex/cache/remote_config.json when the gateway is enabled, and warns (without failing) when run offline.
• docs/features/gateway.md — added an "Offline Behavior" section explaining BYOK vs Gateway offline modes, the cache fallback, the stale warning, and the RemoteConfigUnavailableError cold-cache case.

CHANGELOG [Unreleased] already documents the feature accurately and follows the repo's Keep-a-Changelog style — no voice changes needed.

Documentation Debt

Remaining gap — shipped surface with no coverage in the docs site:

• ⚠️ PIPELEX_REMOTE_CONFIG_URL — the new env var is not documented under docs/configuration/. Reference gap; niche (staging/testing override), low priority.

No architecture diagrams reference the changed modules — no diagram drift.

🤖 Generated with Claude Code

---

Summary by cubic

Adds offline setup, validation, and dry-run for the Pipelex Gateway by caching the remote config to disk and falling back when the service is unreachable; only live inference still needs the network. Also surfaces stale-cache warnings in the agent CLI JSON and prefers a local .pipelex/ project config over the global one.

• New Features

  • Cache the gateway config to ~/.pipelex/cache/remote_config.json, primed on successful fetches and during pipelex init; RemoteConfigFetcher.fetch_remote_config(require_fresh=False) returns RemoteConfigResult { config, source (FRESH|CACHED), cached_at }, and doc/fixture tools use require_fresh=True to refuse cached data.
  • Emit RemoteConfigStaleWarning when falling back to cache and attach it to the agent CLI success envelope as warnings: [...]; disable telemetry on cached configs; BYOK skips remote fetch and runs fully offline; support PIPELEX_REMOTE_CONFIG_URL override.
  • Raise GatewayUnknownModelError when a deck references a missing gateway model, with source-aware hints based on fresh vs cached specs.

• Bug Fixes

  • Recognize .pipelex/ as a project root marker so local config isn’t ignored; harden alias/waterfall resolution with cycle detection and full fallback expansion.
  • Consolidate remote-config failures under RemoteConfigUnavailableError; cached JSON validation issues no longer leak raw errors; preprocess-test-models now propagates require_fresh=True refusals instead of silently generating empty entries.
  • pipelex init cache priming now verifies the cache exists and re-validates the cached payload; if the cache write or validation fails, it reports clear remediation instead of misreporting success.

^{Written for commit 2170259. Summary will update on new commits. Review in cubic}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: dbaa02743d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[greptile-apps]

Greptile Summary

This PR adds offline support for Pipelex Gateway setup, validation, and dry-run flows. The main changes are:

• Schema-versioned remote-config cache under ~/.pipelex/cache/remote_config.json.
• Fresh-or-cached provenance from RemoteConfigFetcher, with fresh-only mode for docs and fixture generation.
• Stale-cache warnings surfaced in agent CLI JSON output.
• Source-aware gateway model validation and user-facing offline error messages.
• Init-time cache priming and .pipelex/ project-root detection.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues found in the changed code.

Important Files Changed

Filename	Overview
pipelex/system/pipelex_service/remote_config_fetcher.py	Adds remote-config provenance, cache fallback, fresh-only refusal, and opportunistic cache writes.
pipelex/system/pipelex_service/remote_config_cache.py	Adds schema-versioned on-disk cache loading and atomic cache writes.
pipelex/pipelex.py	Plumbs gateway config source through setup, emits stale-cache warnings, and disables telemetry for cached specs.
pipelex/cogt/models/model_manager.py	Validates gateway-referenced model handles and resolves aliases/waterfalls with cycle protection.
pipelex/cli/commands/init/command.py	Primes the remote-config cache during init and verifies that the persisted cache is usable.

_{Reviews (8): Last reviewed commit: "fix: re-validate cached payload when pri..." | Re-trigger Greptile}

[cubic-dev-ai]

8 issues found across 36 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="pipelex/cogt/models/model_manager.py">

<violation number="1" location="pipelex/cogt/models/model_manager.py:143">
P2: Gateway membership collection misses extract/img_gen/search choice defaults, so invalid default handles for those model types are not validated.</violation>

<violation number="2" location="pipelex/cogt/models/model_manager.py:183">
P1: Bare HANDLE references are not resolved through alias/waterfall mappings, which can raise `GatewayUnknownModelError` for valid deck references.</violation>

<violation number="3" location="pipelex/cogt/models/model_manager.py:195">
P1: Add cycle detection in the WATERFALL resolution path; without a visited guard, a self-referential or cyclic waterfall can loop indefinitely and hang setup.</violation>

<violation number="4" location="pipelex/cogt/models/model_manager.py:200">
P1: Waterfall membership validation only inspects the first fallback, causing false unknown-model errors when later fallbacks are valid.</violation>
</file>

<file name="pipelex/cli/commands/init/command.py">

<violation number="1" location="pipelex/cli/commands/init/command.py:82">
P2: Cache priming checks gateway enablement from layered/project-preferred config instead of the init target directory, so global vs local init can prime (or skip) based on the wrong backends.toml.</violation>
</file>

<file name="pipelex/pipelex.py">

<violation number="1" location="pipelex/pipelex.py:219">
P2: Do not mark the dummy no-model-specs path as `FRESH`; setting a source here triggers gateway membership validation against empty placeholder specs and can break commands that intentionally skip spec loading.</violation>
</file>

<file name="pipelex/system/pipelex_service/remote_config_fetcher.py">

<violation number="1" location="pipelex/system/pipelex_service/remote_config_fetcher.py:237">
P1: Handle `OSError` around cache persistence so an unwritable `~/.pipelex/cache` does not fail an otherwise successful fresh remote-config fetch.</violation>
</file>

<file name="tests/e2e/agent_cli/test_offline_run_dry.py">

<violation number="1" location="tests/e2e/agent_cli/test_offline_run_dry.py:83">
P3: Parse and return the last JSON object in the CLI output, not the first decodable one, so preamble JSON fragments don't get mistaken for the final agent envelope.</violation>
</file>

_{Tip: cubic can generate docs of your entire codebase and keep them up to date. Try it here.}

[cubic-dev-ai]

1 issue found across 11 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="pipelex/cogt/models/model_manager.py">

<violation number="1" location="pipelex/cogt/models/model_manager.py:243">
P2: Cycle detection in `_collect_candidates` uses only the reference name, so alias/waterfall entries with the same identifier are falsely treated as cycles. This can produce an empty candidate list and incorrectly skip gateway membership validation.</violation>
</file>

_{Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="pipelex/cli/commands/init/command.py">

<violation number="1" location="pipelex/cli/commands/init/command.py:112">
P2: The new priming read-back check treats `RemoteConfigCache.load()` as a usability check, but it only validates the cache wrapper. This can still report `primed=True` with an unusable cached payload.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.
Re-trigger cubic}