Add configurable agent runtime settings

[jeffscottward]

Summary

• add a route-facing session service seam so PI WEB routes stay neutral while the Pi-backed service remains the default
• add configurable Pi-compatible agent command/state settings for diagnostics, status, update checks, auth, models, sessions, and settings
• require an explicit agent state directory for non-pi commands so compatible forks do not silently read Pi state
• document command-specific env var naming, with OMP shown only as one example configuration

Why

PI WEB previously assumed the pi binary and ~/.pi/agent state layout in several backend and UI paths. This keeps PI WEB's embedded session runtime on the bundled SDK path, while making the CLI checks and compatible state/session directories configurable without hardcoding support for one fork.

Verification

• npm run verify
• npm run build
• git diff --check
• Code review subagents: no blockers after follow-up fixes

[jeffscottward]

Local validation completed successfully:

• npm run verify
• npm run build
• git diff --check
• Browser UX smoke with a temporary OMP config

GitHub CI is currently blocked in action_required because this is a fork PR and needs maintainer approval/re-run: https://github.com/jmfederico/pi-web/actions/runs/28221806292

[jeffscottward]

@jmfederico looking to merge this so I can have my Oh-My-Pi flavored version of it by making the underpinning more agnostic :)

[mdcnick]

@jmfederico looking to merge this so I can have my Oh-My-Pi flavored version of it by making the underpinning more agnostic :)

Dude you did what i wanted <3

[jmfederico]

Thank you so much for this. It's fantastic work, and I really appreciate the effort you've put in.

That said, I'm not able to merge it as it stands. Right now it ties things specifically to the OMP fork, and that would make it really hard for me to maintain and properly support over time.

What I'd love instead is to make this more flexible in general, so it can be set up to work with any fork, not just one in particular. I'd be very happy to take it in that direction.

If you're up for reworking it along those lines, I'd be glad to merge then. No pressure at all if not.

Thanks again for getting this started!

[jeffscottward]

@jmfederico I reworked this in commit 8a5ba49 to address your concern about the PR being OMP-specific.

What changed:

• retitled/refocused the PR around configurable agent runtime settings instead of OMP support
• removed the OMP-specific production default/autodetection path
• non-pi commands now require an explicit agent.dir, PI_WEB_AGENT_DIR, or selected command-specific dir env var so forks do not silently read Pi state
• PI_CODING_AGENT_SESSION_DIR fallback is now only used for exact Pi commands; non-Pi commands use their own command-specific session env key
• docs mention OMP only as one example configuration, and the changeset is now a generic patch changeset

Verification completed:

• npm run verify
• npm run build
• git diff --check
• follow-up code review subagents: no blockers

[jmfederico]

@jeffscottward I will get the changes reviewed and tested.

In the meantime, can you help me understand your use case a bit better?
You use OMP, that I gather, and want PI-WEB to use the same data directory that OMP for its config and data.

But, do you expect to take advantage of OMP improvements within PI-WEB?, If so, how would that work? Because PI-WEB continues to use PI's SDK, which means the sessions will continue to be PI's sessions, and will continue to be managed with PI's capabilities, no?

[jmfederico]

My understanding is that OMP has diverged a bit from PI and that it is not 100% compatible. And that sessions, auth and models storage have different shapes.

[jeffscottward]

My understanding is that OMP has diverged a bit from PI and that it is not 100% compatible. And that sessions, auth and models storage have different shapes.

@jmfederico
That would not surprise

I hail from the Maestro team (RunMaestro.ai) and that project has become a bit unwieldy underneath. It was a great effort in the days before "harness engineering" became more of a clear target. We were actually well ahead of Codex UI and Claude Desktop and have continued to be on the cutting edge but there have been far too many regressions for my liking, and wanted a better foundation. Enter Pi. But Pi, is pretty bare bones (on purpose, love that). So then I found OMP, but it lacked a Pi-Web like experience. So without knowing anything about the underpinnings I was trying to submit code that could make that bridge to OMP feasible, and mostly just decorate on top of Pi-Web instead of forking it, and just inherit upstream as much as I could. Your work is great and I am usually allergic to "not invented here" syndrome.

I totally understand if you are unable or unwilling to support multiple paths. I just figured your implementation could be maximally inherited before I had to make hard forks.

[jmfederico]

I am not a OMP user, but I would be more than happy to make pi-web more generic if it is actually useful and stable.

Have you tried your fork end-to-end for extended time?

On a bit of self promotion here, I actually landed on pi running away from over engineered harnessing.

I believe that simpler, but clearer instructions and tooling will give us better AI output.

I drive almost all my AI work through relays: https://relayprinciple.ai/, and it was only possible with pi. Other tools were just getting in the way.

[jeffscottward]

I am not a OMP user, but I would be more than happy to make pi-web more generic if it is actually useful and stable.

Have you tried your fork end-to-end for extended time?

On a bit of self promotion here, I actually landed on pi running away from over engineered harnessing.

I believe that simpler, but clearer instructions and tooling will give us better AI output.

I drive almost all my AI work through relays: https://relayprinciple.ai/, and it was only possible with pi. Other tools were just getting in the way.

I haven't done any forking yet I was waiting for your reply.

The output from Maestro was actually great because it had GitHub's spec kit underneath and bunch of generated todo/phase documents you could clone and run agents against, with a provided session aggregation system that predated /goal.

Just the development of the tool itself became the issue with lack of multiple subscriptions pooling, regressions, etc. The features became too deep to reliably test as well. And then I saw multiple tools in the Pi package ecosystem that added up to what we were doing, which wouldn't be blockers. The features became too large and would block other PR's.

Your relay principles is heavily represented in OMP btw :). The only thing that I had to do was enforce a status handoff document that was it everything else has batteries included.

But anyways back to pi-web.
I suppose yeah including what I already pushed to make it more agnostic would be good, and then I'll do a deep research report on what else should be even more agnostic, build out what you give the OK on, and then I can fork from there?

Off the top of my head without looking at pi-web, I'm imagining a deep OMP settings menu, a tab system with browser preview, file preview, markdown viewer, file directory browser, "playbook specs downloader / loop library explorer", workflow builder (already exists as plugin), "thinking indicators", multi-agent group chat (aka slack channel). You get the picture. It is pretty nice to have "an environment". I do miss it actually.

I've been managing though with the command pallete of WEZTERM and CMD+tab over to Google Chrome and my Finder window, and utilizing a voice notification plug-in. But it's a lot of mental load and coordinating when you start hitting four or five projects. I think the pi ecosystem did need an OMP option, probably others to come?, and it needs a maestro like experience on top of that. This is the chance to do that right.

In my personal projects where you have multiple GitHub repo's of tools that are part of a mono repo of some sort of output you're trying to get out of a tool, I've enforced a sort of hot swappable contracts interface rule. This has helped immensely. Utility layer should be as agnostic as possible and layered on per the needs of each path. Your concerns about the OMP data model is absolutely noted here.

Anyways that was quite a brain dump. The type of thing I like to do for an AI's context.

I'll go run the analysis and report back soon. Probably compare Graphify maps or something.

[jeffscottward]

I ran the follow-up analysis from the latest thread and opened it as a separate report issue so this PR does not keep expanding in scope:

• Report issue: Report: provider-agnostic pi-web seams for future OMP distribution #40
• Markdown + HTML document files: https://gist.github.com/jeffscottward/8f09a07fb79b06e0845bfc910f172d4b

Short version: I think PR #36 is the right low-risk slice if it stays framed as configurable Pi-compatible command/state-dir seams, not OMP support. The report recommends keeping upstream pi-web small and Pi-default, adding only narrow provider/capability/plugin seams over time, and building the Maestro-like OMP environment downstream first as an adapter/distribution/plugin set.

[jeffscottward]

@jmfederico ?

[jmfederico]

Hi

I am on a trip with limited availability. This is a the top of my todo, will retake it next week, July Monday 13.

[jmfederico]

Work is ongoing to get this ready for release

[jmfederico]

@jeffscottward Thank you for your patience and for starting this work. I completed a substantial maintainer-side rework on top of your contribution, preserving your attribution, and it has now merged as #57.

The supported scope is deliberately narrow:

• PI WEB can select a Pi-compatible agent profile and companion CLI.
• The embedded session runtime remains the bundled Pi SDK; this is not runtime swapping.
• Sessiond owns an immutable active profile for its lifetime. Settings saves the desired command and directory together and shows when a restart is required.
• Sessions, Pi packages, package-backed plugins, status/install detection, and update planning consistently use the daemon-owned active profile.
• Unsafe commands and paths are rejected, arbitrary command-derived environment variables are not inferred, and mixed-version remotes cannot report false-successful profile saves.

This does not claim support for OMP's divergent data formats or capabilities, and it does not migrate profile data or PI WEB archives. Downstream OMP work can build on this seam where it remains compatible with the Pi SDK, while OMP-specific behavior stays downstream.

Final verification passed on Linux and Windows CI, in addition to the focused isolated-profile and mixed-version coverage.

Thank you again—this PR and your follow-up analysis were the starting point for the maintainable version that landed. I am closing this PR as superseded by #57.

[jeffscottward]

Great thanks for that!