Skip to content

feat(integrations): keep host plugins thin and make them work behind the gateway #2250

Open

Description

@Fengzdadi

Feature description

Keep host plugins thin, and make them work when the host's model traffic goes through the gateway (#2199).

A plugin does what only the host can do: handle session events, bind the workspace to a Scope, configure tools, and show diagnostics. When the host's model traffic goes through the gateway, the gateway prepares, injects, checks, and captures each turn, and the plugin leaves that work to it. Where the gateway does not carry a host's model traffic, the plugin keeps delivering prompt-time context itself. Helpers that several plugins share are generated from one source.

Problem and proposed solution

Problem

A plugin and the gateway cannot both be on the model path. Core's before_send check requires every BEGIN_POWERCONTEXT_PREPARED_CONTEXT_V1 or BEGIN_POWERCONTEXT_PREPARED_TEXT_V1 block in a request to be declared and bound. The gateway declares only the block it injects. A plugin's block is never declared, and a plugin cannot tell that the gateway owns the turn: context_owner from #2199 is not implemented, and no plugin has a setting for it.

I ran the Codex plugin against upstream/master at 9c8f061 with Codex 0.166.0-alpha.5.1, the gateway in the combined deployment (PC_GATEWAY_CORE_UDS), an enforcing Server, and a local recording upstream. Each setup sent two messages in one thread:

Setup Prepares per message, plugin / gateway Result
Plugin, model called directly 1 / 0 Both turns complete.
Gateway, no plugin 0 / 1 Both turns complete.
Plugin and gateway, default injection 1 / 1 Every check returns 422, which the Server log names context-binding-required. The gateway answers 503 gate_paused, Codex sends 30 requests per message, and the turn fails. The upstream receives nothing.
Plugin and gateway, PC_GATEWAY_INJECTION=off 1 / 0 The same failure: the plugin's block alone is rejected.

The gateway uses one Scope. It takes the Scope only from PC_GATEWAY_DEFAULT_SCOPE; #2199 limits the first version to a single Scope. A plugin binds each workspace to its own Scope, but the gateway prepares and captures every conversation in that one Scope.

Proposal

Each part does the work whose inputs only it has:

Part Owns
Host plugin Session events: startup, resume, fork, and compaction. Resolving and binding the Scope from the workspace. Tool configuration. Diagnostics shown in the host. Bootstrap context at session start. Prompt-time context and prompt capture, only where the gateway does not carry the host's model traffic.
Gateway For the traffic it carries: preparing and injecting prompt-time context, the complete-request checks, replay, and capturing turns.
Server Retrieval, rendering, trust wrapping, persistence, bindings, and the check rules.

One owner per turn. When the host's model traffic goes through the gateway, the plugin neither prepares nor injects prompt-time context, and the gateway captures the turn (PC_GATEWAY_SEDIMENT=on) instead of the plugin. A plugin setting turns prompt-time recall off. For Codex it is POWERCONTEXT_CODEX_PROMPT_RECALL=false, next to the existing POWERCONTEXT_CODEX_CAPTURE_PROMPTS. The setting lives in the plugin because only the host's configuration knows, before a turn starts, where its model request will go.

The rest of the plugin keeps working behind the gateway:

  • The gateway forwards Core and /mcp routes, so its address works as the plugin's Server URL. In the run above, binding, prepare, capture, and the Codex MCP tools all went through the gateway's port.
  • Core's check covers only the two prepared-context markers. The bootstrap block uses BEGIN_POWERCONTEXT_BOOTSTRAP_CONTEXT_V1, so SessionStart bootstrap is not affected. This is from the code; the run kept bootstrap off, the plugin default.
  • Bootstrap, including a committed Handoff, stays in the plugin until the gateway takes it on.

Plugins keep the fallback. The gateway does not carry:

  • Claude Code, which uses the Messages API. docs(rfc): define Rust PowerContext Gateway #2199 lists /gateway/v1/messages as a later route.
  • Hosts signed in with a subscription account. The gateway calls the upstream with a key from its own environment.
  • Setups without the gateway, which is optional and disabled by default.

There the plugin keeps preparing, injecting, and capturing as it does today.

The Scope crosses through the Server. The plugin's half already exists. At session start, the Codex plugin writes a session binding, {"integration": "codex", "kind": "session", "external_id": <session_id>}, with PUT /v1/scope-bindings, unless an explicit Scope is configured. In every recorded session, the hook's session_id was the thread-id that Codex sends and that the gateway reads as the conversation identity (#2419). The gateway's half is the first follow-up below.

Plan

Done:

In review:

Next, in order:

  1. Codex: POWERCONTEXT_CODEX_PROMPT_RECALL (feat(codex): add a setting that turns prompt-time recall off #2453), default true. With false, the UserPromptSubmit hook sends no prepare request and injects nothing. Run with a real Codex behind the gateway, through the pass-through shim until bug(inference): an unmodified Codex 0.145 cannot complete a turn through an enforcing Server #2420 is fixed.
  2. Codex through the gateway, in the Codex guide once bug(inference): an unmodified Codex 0.145 cannot complete a turn through an enforcing Server #2420 is fixed: point Codex at /gateway/v1; set POWERCONTEXT_CODEX_PROMPT_RECALL=false and POWERCONTEXT_CODEX_CAPTURE_PROMPTS=false; turn on PC_GATEWAY_SEDIMENT; set PC_GATEWAY_DEFAULT_SCOPE to the workspace's Scope; and approve provider-default cache retention on the upstream target, because Codex always sends prompt_cache_key.
  3. SessionStart on the shared package (refactor(integrations): run the Claude Code and Codex SessionStart flow from the lifecycle package #2550): the Claude Code and Codex plugins ship the package, and the diagnostic throttle, bootstrap receipts, bounded HTTP, and the SessionStart flow move into it.
  4. UserPromptSubmit on the shared package: Claude Code and Codex keep this flow as the fallback, so the Scope client and the prompt flow, including the new setting, move into the package.
  5. Other plugins whose hosts can send model traffic to the gateway get the same setting when their gateway setup is documented.

Adapter-side trust notices, independent of the steps above: one PR per adapter, except that the five Python adapters share one PR. Trust wrapping belongs to the Server, which already puts TRUST_POLICY (src/powercontext/builtin/runtime/prepared_text.py, since #28) ahead of the historical items in every prepared context; code excerpts carry their own untrusted-data line. Each adapter drops the trust sentence it adds on top, and keeps any marker it uses to recognize its own injections. Each PR checks whether the adapter's wording says something TRUST_POLICY does not, and states how that is handled.

Shared TypeScript helpers follow the Python ones: one source in integrations/lifecycle/, with a generated copy at each plugin's current path, so bundles and published packages stay as they are (#2623). Helpers whose copies have diverged move one at a time, each after a host parameter or a separate behavior PR settles the difference. The Kimi Code and ZCode .mjs hooks join with the first helper they share with the TypeScript plugins.

Not planned: moving each host's full lifecycle into a shared module (Hermes included).

Compatibility

  • Without the new setting, every plugin behaves as it does today.
  • With POWERCONTEXT_CODEX_PROMPT_RECALL=false, the Codex plugin sends no prepare request and injects no block. Bootstrap, bindings, tools, prompt capture, and diagnostics keep their own settings.
  • Settings, local state, and workspace keys keep their names, paths, and derivation.
  • No Server API changes.

Verification

  • The characterization fixtures from test(integrations): characterize the Claude Code and Codex hooks #2255 stay unchanged with the default setting. New fixtures cover false.
  • A real Codex with the plugin, the gateway, and the setting completes each turn, with one gateway prepare per message and one block in the upstream request.
  • Each PR says which hosts were actually run, and whether its payloads were recorded or synthetic.

Non-goals

  • Changes under gateway/. The follow-ups below are for its owners.
  • A universal cross-host hook API, or a runtime dependency between installed packages.
  • Changing how workspace keys are derived.

Gateway follow-ups

Observations from the run. The plugin work does not depend on them.

  • Scope per conversation. The gateway could resolve the Scope with POST /v1/scope-bindings/resolve and the session binding above, falling back to PC_GATEWAY_DEFAULT_SCOPE. No new endpoint is needed.
  • The error for an undeclared block. The gateway turns Core's 422 into 503 gate_paused and logs nothing about it. Codex retries the 503 30 times per message and shows only gate rejected: HTTP 422. A response that names the cause would point users at the fix.

Alternatives considered

  • One module per language for every host's full lifecycle. Each plugin would keep carrying the prompt-time work that the gateway takes over for the hosts it serves.
  • Disable the plugin's UserPromptSubmit hook in Codex's /hooks. It needs no code, but it depends on each Codex build's hook controls, which this repository does not test.
  • A Server-wide context_owner that plugins read. It would also silence hosts the gateway does not carry, such as Claude Code.
  • The gateway drops blocks it did not inject. Plugins would still prepare and capture every turn, and the gateway would silently edit client input.
  • The gateway infers the owner from blocks already in the request. docs(rfc): define Rust PowerContext Gateway #2199 rules this out: a matching prompt tag does not prove host ownership. The check would also still reject the plugin's block, as the run with PC_GATEWAY_INJECTION=off shows.
  • Remove prompt-time context from plugins. Hosts the gateway does not carry would lose recall.

Additional context

  • Code facts are from upstream/master at 9c8f061: the check markers in src/powercontext/builtin/runtime/context_check.py; the Scope, routes, and upstream key in gateway/crates/pc-gateway-app/src/ingress.rs and main.rs; the session binding in integrations/codex/plugins/powercontext/hooks/session_binding.py and scripts/scope_binding.py.
  • The run used real Codex, Server, and gateway processes, with a recording upstream and a recording proxy in front of the gateway. I can share the scripts and recordings.

Are you willing to contribute to this feature?

  • Yes, I am willing to contribute code, docs, or design feedback.

I'll do the plugin side, starting with the Codex setting. Please comment here before starting on any item, so the work isn't duplicated.

Activity

  1. Fengzdadi commented on Oct 26, 2026

    @Fengzdadi
    ContributorAuthor

    @PsiACE, here is the location question from the issue in concrete form, so it can be answered with a yes or no.

    I'd like to start step 3 with this layout:

    src/powercontext_integration_lifecycle/      # new top-level package, standard-library only
    ├── __init__.py
    ├── client_config.py       # source of powercontext_client_config.py (Claude Code, Codex, Hermes, WorkBuddy)
    ├── prepared_context.py    # source of hooks/prepared_context.py (Claude Code, Codex, WorkBuddy)
    ├── prompt_privacy.py      # source of hooks/prompt_privacy.py (Claude Code, Codex, WorkBuddy)
    └── bootstrap_context.py   # source of hooks/bootstrap_context.py (Claude Code, Codex)
    scripts/generate_integration_lifecycle.py    # `make integration-lifecycle` writes the 12 copies; `--check` runs in `make check`
    
    • The package is added to the wheel's packages, next to src/powercontext_service_bootstrap. It stays out of powercontext.client, so it is not SDK API, is not in the Python API reference, and needs no client extra.
    • The copies stay where each plugin imports them today and gain only a generated-file header. No plugin's layout, installation, or behavior changes, and the Claude Code and Codex characterization fixtures from test(integrations): characterize the Claude Code and Codex hooks #2255 pass unchanged.
    • Settings, transport policy, Scope resolution, capture, flush, and diagnostics move into the same package in later PRs, one host per PR.

    OK to go ahead with this layout? If you'd rather have it under src/powercontext/client/lifecycle/, I'll use that path; the prototype already works there.

  2. Fengzdadi commented on Oct 27, 2026

    @Fengzdadi
    ContributorAuthor

    Two other directions are worth settling before step 3, together with where the Python module lives.

    One language for every plugin. Nine of the 14 hosts on the automatic path run the adapter inside the host process, so the host fixes the language: Hermes, Bub, LangChain, LangGraph, and Pydantic AI are Python; Pi, OpenCode, OpenClaw, and DSH are TypeScript. Only the five command-hook hosts can choose. Claude Code, Codex, and WorkBuddy run Python hooks, and Kimi Code and ZCode run .mjs hooks. Both implementations therefore stay, and moving a command-hook host to the other language would not remove either of them. Which language each command-hook host uses can be decided per host later, by which runtime that host can rely on. The fixtures in #2255 record only what crosses the process boundary, so they could check such a port as they are.

    A fat client. If every plugin called one local client, there would be one implementation, and each plugin would only forward events. The costs:

    • Every plugin would depend on a separately installed component, at a version that matches both the plugin and the Server. That is the "shared package that every plugin installs" alternative in the issue, and its "runtime dependency between installed packages" non-goal.
    • The protocol between plugins and the client would be a universal cross-host hook API, which the issue also lists as a non-goal.
    • The nine in-process hosts call the Server directly today and would gain a hop. Each command hook would also spend the client's startup time inside its request budget, which is 1 s for Kimi Code and ZCode.

    The fat client and this plan don't exclude each other. Once each language has one module, a command hook could call an installed hook command that wraps that module, if setup can guarantee the command exists. I'd treat that as a possible later step, not as an alternative to this plan.

    Where the Python module lives. The module is the single source of the host-side lifecycle code. In step 3 it reaches users only as copies inside plugins, and framework adapters may import it later. So it has to import with the standard library alone, run on Python 3.9 (the Claude Code copy often runs on the macOS system Python), and stay out of the SDK's public API.

    • src/powercontext/client/lifecycle/ misses these. Importing it runs powercontext/client/__init__.py, which imports httpx. It would also be published in the Python API reference, and its normalize_server_url behaves differently from the SDK function of the same name.
    • A top-level package, src/powercontext_integration_lifecycle/, meets all of them, following the precedent of src/powercontext_service_bootstrap.
    • An unpackaged source directory under integrations/ would also meet them, but adapters could not import it from the installed package.

    One caveat: powercontext-langchain, powercontext-langgraph, powercontext-pydantic-ai, and powercontext-bub are released separately and depend on powercontext[client] without pinning a version (Pydantic AI requires only >=0.0.3). Once an adapter imports the module, the module becomes an interface between separately released packages, as powercontext.client.transport_policy is today. The first step-3 PR has no such consumer, so importing versus copying can be decided when an adapter moves.

    @PsiACE, unless you'd rather have it under powercontext.client, or someone wants an RFC first, I'll open the first step-3 PR with the top-level package after #2255 merges: the module, the generate/check command, and the 12 generated copies. Moving it later is a path change.

  3. Fengzdadi commented on Oct 31, 2026

    @Fengzdadi
    ContributorAuthor

    Progress update.

    Merged

    Waiting for review

    Their failing checks also fail on master 0c1dfc2, apart from a ZCode e2e case on #2317 and a Windows managed-resource smoke timeout on #2318. Neither looks related to these changes.

    Ready after #2318 and #2317 merge

    The rest of the Python pilot moves Claude Code and Codex onto the module in two PRs:

    1. SessionStart: both plugins ship the module as a powercontext_lifecycle/ package. The diagnostic throttle, bootstrap receipts, bounded HTTP, and the SessionStart flow move into it, and the SessionStart hooks keep only a host shell.
    2. Prompt hooks: the Scope client and the UserPromptSubmit flow move into the package, and the prompt hooks keep only a host shell.

    Both leave the characterization fixtures unchanged and add shell tests built from recorded native payloads. The prompt-hook PR changes one behavior: Codex no longer skips prompt capture when recall raises an error the flow does not classify. Claude Code already captures in that case, and both integration guides say recall and capture fail independently.

    With #2318 and #2317 underneath, both PRs ran on real hosts against a local Server: Claude Code 2.1.277, with its hooks on Python 3.9, and Codex 0.166.0-alpha.5.1. In Claude Code, startup, resume, fork, and compact injected the bootstrap package; in Codex, startup, resume, and fork did. Prompt recall returned a Memory that only recall could reach, and prompts were captured. With a missing Scope, both hosts showed the new scope_resolve diagnostic and sent no prepare or capture request. With the Server stopped, the first prompt showed server_unavailable.

    Not started

    • Step 2: removing adapter-side trust notices, one PR per adapter, keeping any marker an adapter uses to recognize its own injections.
    • Step 3: Hermes, and the TypeScript pilot. feat(integrations): enforce pre-compaction lifecycle contracts #2180 has merged, so the Pi and OpenClaw flush acknowledgement can move once the TypeScript question in the issue is answered.

    Reviews of #2317 and #2318 would unblock the two step-3 PRs.

  4. changed the title [-]feat(integrations): give the automatic integration lifecycle one implementation per language[/-] [+]feat(integrations): keep host plugins thin and make them work behind the gateway[/+] on Nov 3, 2026
  5. Fengzdadi commented on Nov 3, 2026

    @Fengzdadi
    ContributorAuthor

    I've re-scoped this issue around the gateway (#2199). On master, a host plugin and the gateway cannot both be on the model path: with the Codex plugin behind the gateway, every turn failed, and turning gateway injection off didn't help. The table is in the body.

    The issue now covers three things: plugins leave prompt-time context and capture to the gateway when the host's model traffic goes through it, starting with a Codex setting; plugins keep prompt-time context as the fallback where the gateway does not carry the traffic; and the parts that plugins share are generated from one source. Moving every host's full lifecycle into a shared module is no longer planned. #2317, #2318, and #2322 are unchanged, and the Codex setting is the next PR.

    @hidb4ai @jasper-yl, for awareness: the body lists two gateway-side follow-ups from the run. The plugin work doesn't depend on them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions