@modootoday/pmcp 0.17.4 → 0.18.2
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/.agents/plugins/marketplace.json +1 -1
- package/.claude-plugin/marketplace.json +1 -1
- package/.claude-plugin/plugin.json +2 -2
- package/.mcp.json +1 -1
- package/CHANGELOG.md +152 -0
- package/CONTRIBUTING.md +71 -0
- package/README.md +98 -201
- package/SECURITY.md +17 -1
- package/dist/apply-JUTGS5WZ.js +242 -0
- package/dist/{attachment-tU5FZrgZ.d.ts → attachment-D84OGI6n.d.ts} +1 -1
- package/dist/available-DBSIVVJ6.js +73 -0
- package/dist/broadcast-CBMVOV3G.js +18 -0
- package/dist/chunk-26WLNWDG.js +93 -0
- package/dist/chunk-2FIV63WC.js +252 -0
- package/dist/chunk-2P4Z2NUX.js +28 -0
- package/dist/chunk-34DECPVC.js +22 -0
- package/dist/chunk-3FCFAQDG.js +42 -0
- package/dist/chunk-3IDXEV5E.js +1934 -0
- package/dist/chunk-3PW4FI7U.js +32 -0
- package/dist/chunk-3Y3HDMHA.js +108 -0
- package/dist/chunk-47O3X4VS.js +113 -0
- package/dist/chunk-4NDEP7HU.js +26 -0
- package/dist/chunk-5OMOPUE6.js +39 -0
- package/dist/chunk-5QQWS4US.js +53 -0
- package/dist/chunk-5ZABTVSW.js +48 -0
- package/dist/chunk-65KAQSJP.js +7 -0
- package/dist/chunk-6STKGOCW.js +27 -0
- package/dist/chunk-6WXMJOMI.js +9 -0
- package/dist/chunk-73AKO4UL.js +24 -0
- package/dist/chunk-7DLZC73N.js +29 -0
- package/dist/chunk-7GBYECSK.js +72 -0
- package/dist/chunk-7HFIGCSL.js +419 -0
- package/dist/chunk-7TD53M7L.js +13 -0
- package/dist/chunk-7UCZAN4J.js +778 -0
- package/dist/chunk-A4PKLESO.js +112 -0
- package/dist/chunk-A7VF7A35.js +1025 -0
- package/dist/chunk-ABTJQ4QV.js +74 -0
- package/dist/chunk-AJ4VXM2U.js +349 -0
- package/dist/chunk-BBTBJCFA.js +380 -0
- package/dist/chunk-BU65MNVU.js +13 -0
- package/dist/chunk-C4NHQGHL.js +142 -0
- package/dist/chunk-CJTKR6K6.js +1213 -0
- package/dist/chunk-D77IRGHO.js +1246 -0
- package/dist/chunk-DCU2EXQV.js +78 -0
- package/dist/chunk-DMZHQZ7P.js +104 -0
- package/dist/chunk-DZ2MRTYT.js +135 -0
- package/dist/chunk-E2YOZ2FF.js +207 -0
- package/dist/chunk-E3DQB5LS.js +48 -0
- package/dist/chunk-EATCUWGG.js +66 -0
- package/dist/chunk-EAWPJHJ7.js +155 -0
- package/dist/chunk-EIDIVIAD.js +33 -0
- package/dist/chunk-F5QYZK7E.js +396 -0
- package/dist/chunk-F5XMGOOX.js +28 -0
- package/dist/chunk-FENOGX3U.js +31 -0
- package/dist/chunk-GZHHEHKY.js +44 -0
- package/dist/chunk-HDMBVLCZ.js +53 -0
- package/dist/chunk-HQOB7OQS.js +81 -0
- package/dist/chunk-I2ZP2PSA.js +211 -0
- package/dist/chunk-IG33DXLT.js +151 -0
- package/dist/chunk-IJBSOWHK.js +86 -0
- package/dist/chunk-INT7QLEU.js +114 -0
- package/dist/chunk-J7UYNJCR.js +9 -0
- package/dist/chunk-JEL35P7S.js +53 -0
- package/dist/chunk-JGJ4INEN.js +32 -0
- package/dist/chunk-JS5RTH4I.js +84 -0
- package/dist/chunk-JWRZDYB5.js +59 -0
- package/dist/chunk-KMXRRSKT.js +660 -0
- package/dist/chunk-LBXO4VPG.js +73 -0
- package/dist/chunk-LLBPVZXM.js +67 -0
- package/dist/chunk-LLT5FQBE.js +57 -0
- package/dist/chunk-LMT3PPXJ.js +17 -0
- package/dist/chunk-LMUBBIE2.js +83 -0
- package/dist/chunk-LTZH5E3G.js +479 -0
- package/dist/chunk-LW4TG7EL.js +39 -0
- package/dist/chunk-MPSQXSC6.js +346 -0
- package/dist/chunk-MVFH26QT.js +97 -0
- package/dist/chunk-NLEXKE7U.js +67 -0
- package/dist/chunk-NQPURJT5.js +44 -0
- package/dist/chunk-NRBQK6UX.js +105 -0
- package/dist/chunk-OEH47H6A.js +48 -0
- package/dist/chunk-OG7QR2DP.js +75 -0
- package/dist/chunk-OPYFEHKG.js +52 -0
- package/dist/chunk-P4N7DBD5.js +83 -0
- package/dist/chunk-PAX3QXX2.js +140 -0
- package/dist/chunk-PKODFR5F.js +102 -0
- package/dist/chunk-PMJG2CXF.js +122 -0
- package/dist/chunk-Q5H3L6Y4.js +23 -0
- package/dist/chunk-QEF7EK3T.js +28 -0
- package/dist/chunk-QEW4J3IZ.js +74 -0
- package/dist/chunk-QPL7E2HW.js +464 -0
- package/dist/chunk-R2GPCZUX.js +22 -0
- package/dist/chunk-R5MT42JS.js +284 -0
- package/dist/chunk-RMATE45Z.js +197 -0
- package/dist/chunk-RPQOBHVU.js +87 -0
- package/dist/chunk-S3PIAMXV.js +230 -0
- package/dist/chunk-T3LKX23M.js +168 -0
- package/dist/chunk-T6GOWHK6.js +30 -0
- package/dist/chunk-TIA4SPU2.js +10 -0
- package/dist/chunk-TNCZ6444.js +57 -0
- package/dist/chunk-TVL5RTE6.js +269 -0
- package/dist/chunk-TXQ7L33K.js +45 -0
- package/dist/chunk-UPQTAHUK.js +189 -0
- package/dist/chunk-V4NPDK6X.js +14 -0
- package/dist/chunk-VJFEN6DJ.js +38 -0
- package/dist/chunk-VMHUEOT5.js +643 -0
- package/dist/chunk-VRPMYPZU.js +4985 -0
- package/dist/chunk-WIW772I3.js +25 -0
- package/dist/chunk-XELAZAIM.js +136 -0
- package/dist/chunk-XNML2KIC.js +23 -0
- package/dist/chunk-XP2U3LO3.js +30 -0
- package/dist/chunk-YGOWIJPE.js +51 -0
- package/dist/chunk-YIXDHQYE.js +11 -0
- package/dist/chunk-YSAWTGNA.js +117 -0
- package/dist/claude-U2JC2DNQ.js +77 -0
- package/dist/cli-MI4ZCAZ3.js +41 -0
- package/dist/cli-ZN7ZVDEZ.js +46 -0
- package/dist/cli.js +144 -16197
- package/dist/completion-ILSRB3LW.js +142 -0
- package/dist/config-DnpLL2kT.d.ts +46 -0
- package/dist/{service-qpCsOXkQ.d.ts → core-C1LPjxK6.d.ts} +2 -6
- package/dist/diagnostics-XKXVVQWH.js +93 -0
- package/dist/doctor-O2E63YGO.js +538 -0
- package/dist/entry-X6CSYQRQ.js +305 -0
- package/dist/exec-mcp-2PMWBPD7.js +365 -0
- package/dist/harness-L2KSI2ZB.js +177 -0
- package/dist/harness-egress-bridge.js +4 -4
- package/dist/harness-launch-gate.js +47 -940
- package/dist/harness-pane-runner.js +13 -80
- package/dist/harness-worker.js +21 -2703
- package/dist/hook-body.js +5222 -0
- package/dist/hook-spec-C5fWTSCH.d.ts +100 -0
- package/dist/hook.js +26 -0
- package/dist/hooks-BHTA44X7.js +21 -0
- package/dist/host-UIZAXXQH.js +22 -0
- package/dist/host-UWK754BW.js +210 -0
- package/dist/host-run-BI2OTZDZ.js +307 -0
- package/dist/http.d.ts +5 -42
- package/dist/http.js +21 -2234
- package/dist/import-mcp-GPKJI7DI.js +400 -0
- package/dist/index.d.ts +146 -168
- package/dist/index.js +133 -4948
- package/dist/init-3C2Y7BNJ.js +14 -0
- package/dist/install-GG7HHZK2.js +796 -0
- package/dist/invoke-44CJRVMK.js +23 -0
- package/dist/list-MCP2FXUF.js +68 -0
- package/dist/list-WL6L4J5H.js +65 -0
- package/dist/load-BEUBABtB.d.ts +21 -0
- package/dist/logout-F5EJ5MOU.js +44 -0
- package/dist/logs-TBUA4UWU.js +107 -0
- package/dist/mailbox/index.d.ts +10 -5
- package/dist/mailbox/index.js +53 -1572
- package/dist/mailbox-BMTZOSZ7.js +285 -0
- package/dist/mailbox-GDJ7BWQN.js +189 -0
- package/dist/mainline-KAD2ERLP.js +639 -0
- package/dist/marketplace-G4VQET5W.js +191 -0
- package/dist/mcp-235QZN2A.js +15 -0
- package/dist/mcp-FJ2UQ4RH.js +193 -0
- package/dist/models-ISU4DCMA.js +32 -0
- package/dist/opencode-CN7JLQYO.js +60 -0
- package/dist/pause-7LILUVGL.js +18 -0
- package/dist/preview-DT7DWG5F.js +91 -0
- package/dist/project/hook-adapter.d.ts +5 -2
- package/dist/project/hook-adapter.js +41 -27
- package/dist/project-5YV5CUEG.js +70 -0
- package/dist/pty-XTJ4MIWK.js +94 -0
- package/dist/recovery-U6QB3PMT.js +100 -0
- package/dist/reindex-Y27QJFDB.js +22 -0
- package/dist/resume-26VFAAMH.js +18 -0
- package/dist/run-3AXTZSR7.js +126 -0
- package/dist/run-3SOVRQIA.js +19 -0
- package/dist/serve-DQMKTFIV.js +104 -0
- package/dist/session-XM2CR425.js +159 -0
- package/dist/setup-DTKZLZUT.js +18 -0
- package/dist/start-login-YTZV6KMF.js +416 -0
- package/dist/status-A2OUTNGK.js +9 -0
- package/dist/status-H2VAHIDV.js +10 -0
- package/dist/status-MROQ7WR7.js +43 -0
- package/dist/status-RO55QPKV.js +55 -0
- package/dist/status-UME2L33L.js +286 -0
- package/dist/stdio.d.ts +3 -13
- package/dist/stdio.js +16 -3186
- package/dist/sweep-35LGQTTO.js +18 -0
- package/dist/test-AGZOJLRZ.js +561 -0
- package/dist/tools-gpHNq9Dh.d.ts +328 -0
- package/dist/tui-G5LLWCSV.js +153 -0
- package/dist/unbroadcast-5QNGAJR2.js +18 -0
- package/dist/validate-IU52H2IC.js +46 -0
- package/dist/worker-QZ5T6LJD.js +80 -0
- package/dist/worktree-create-PZSRB7PH.js +89 -0
- package/dist/worktree-list-JYB6VXLW.js +51 -0
- package/dist/worktree-sync-UF5CXPWV.js +30 -0
- package/docs/authoring.md +82 -0
- package/docs/browser-and-desktop.md +46 -0
- package/docs/commands.md +325 -0
- package/docs/compare.md +35 -0
- package/docs/compatibility.md +55 -0
- package/docs/embeddings.md +1 -1
- package/docs/getting-started.md +105 -0
- package/docs/git-workflow.md +60 -0
- package/docs/glossary.md +31 -0
- package/docs/hooks/capabilities/antigravity.json +199 -0
- package/docs/hooks/capabilities/claude.json +179 -0
- package/docs/hooks/capabilities/codex.json +179 -0
- package/docs/hooks/capabilities/gemini.json +196 -0
- package/docs/hooks/capabilities/grok.json +192 -0
- package/docs/hooks/capabilities/opencode.json +184 -0
- package/docs/hooks.md +264 -0
- package/docs/install.md +72 -0
- package/docs/library-skills.md +132 -0
- package/docs/mailbox.md +16 -5
- package/docs/project-configuration.md +540 -58
- package/docs/sessions.md +64 -0
- package/docs/skills.md +4 -45
- package/docs/terminal-harness.md +92 -44
- package/docs/terminal-workspace.md +81 -169
- package/gemini-extension.json +2 -2
- package/mcp.json +1 -1
- package/package.json +16 -2
- package/plugin.json +2 -2
- package/plugins/pmcp/.claude-plugin/plugin.json +4 -2
- package/plugins/pmcp/.mcp.json +1 -1
- package/plugins/pmcp/gemini-extension.json +2 -2
- package/plugins/pmcp/mcp.json +1 -1
- package/plugins/pmcp/mod/commands.ts +72 -0
- package/plugins/pmcp/mod/contract.d.ts +39 -0
- package/plugins/pmcp/mod/draw.tsx +216 -0
- package/plugins/pmcp/mod/guard.ts +42 -0
- package/plugins/pmcp/mod/hooks.json +4 -0
- package/plugins/pmcp/mod/host.ts +46 -0
- package/plugins/pmcp/mod/model.ts +144 -0
- package/plugins/pmcp/mod/reader/index.ts +18 -0
- package/plugins/pmcp/mod/reader/read.ts +76 -0
- package/plugins/pmcp/mod/reader/settings.ts +54 -0
- package/plugins/pmcp/mod/reader/types.ts +38 -0
- package/plugins/pmcp/mod/register.tsx +73 -0
- package/plugins/pmcp/mod/sessions/format.ts +91 -0
- package/plugins/pmcp/mod/sessions/types.ts +162 -0
- package/plugins/pmcp/mod/snapshot.ts +75 -0
- package/plugins/pmcp/mod/spinner.tsx +30 -0
- package/plugins/pmcp/mod/state.ts +28 -0
- package/plugins/pmcp/plugin.json +2 -2
- package/plugins/pmcp/skills/agent-assets-migrate/SKILL.md +96 -0
- package/plugins/pmcp/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
- package/plugins/pmcp/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/plugins/pmcp/skills/package-skill-catalog/SKILL.md +51 -15
- package/plugins/pmcp/skills/pmcp-browser/SKILL.md +27 -0
- package/plugins/pmcp/skills/pmcp-desktop/SKILL.md +25 -0
- package/plugins/pmcp/skills/pmcp-project-init/SKILL.md +153 -0
- package/plugins/pmcp/skills/pmcp-sessions-and-git/SKILL.md +96 -0
- package/plugins/pmcp/skills/skill-package-scaffold/SKILL.md +89 -0
- package/schema/catalog-v1.json +187 -0
- package/schema/library.json +196 -0
- package/schema/marketplace-manifest.json +144 -0
- package/schema/plugin-manifest.json +59 -0
- package/schema/skill-frontmatter.json +170 -0
- package/schema/skill-metadata-core.json +131 -0
- package/skills/agent-assets-migrate/SKILL.md +96 -0
- package/skills/headless-agents-ci-scaffold/SKILL.md +101 -0
- package/skills/marketplace-plugin-scaffold/SKILL.md +87 -0
- package/skills/package-skill-catalog/SKILL.md +51 -15
- package/skills/pmcp-browser/SKILL.md +27 -0
- package/skills/pmcp-desktop/SKILL.md +25 -0
- package/skills/pmcp-project-init/SKILL.md +153 -0
- package/skills/pmcp-sessions-and-git/SKILL.md +96 -0
- package/skills/skill-package-scaffold/SKILL.md +89 -0
- package/dist/config-BkSpjUG6.d.ts +0 -50
- package/dist/embed-DRROSD3F.d.ts +0 -53
- package/dist/hook-spec-CSJJySsH.d.ts +0 -11
- package/dist/server-VWSY3Shw.d.ts +0 -543
- package/dist/tui-worker.js +0 -6549
- package/docs/manual-library-skills.md +0 -74
- /package/dist/{tui-worker.d.ts → hook.d.ts} +0 -0
package/docs/sessions.md
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
# Run several agents in one repository
|
|
2
|
+
|
|
3
|
+
[Back to the overview](../README.md)
|
|
4
|
+
|
|
5
|
+
Two agents editing one checkout overwrite each other, push half-finished work or reinstall
|
|
6
|
+
dependencies under each other's feet. pmcp lets every agent session in a repository see the
|
|
7
|
+
others, and gives you the controls to coordinate them: a session list, a pause, broadcasts,
|
|
8
|
+
addressed messages, leases on shared files, linked worktrees and one delivery path to the
|
|
9
|
+
mainline. Every part is opt-in through `pmcp.toml`; the keys are in the
|
|
10
|
+
[pmcp.toml reference](project-configuration.md#sessions).
|
|
11
|
+
|
|
12
|
+
## See who is working
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
pmcp sessions status
|
|
16
|
+
```
|
|
17
|
+
|
|
18
|
+
It lists each live session (id, runtime, checkout and current tool), the pause, current
|
|
19
|
+
broadcasts, held leases, and files edited but not yet delivered in the shared checkout.
|
|
20
|
+
`pmcp status` adds projection drift and worktree ahead and behind counts.
|
|
21
|
+
|
|
22
|
+
## Pause and broadcast
|
|
23
|
+
|
|
24
|
+
These are your controls; an agent reports the need for them and leaves the decision to you.
|
|
25
|
+
|
|
26
|
+
```sh
|
|
27
|
+
pmcp sessions pause "release freeze"
|
|
28
|
+
pmcp sessions resume
|
|
29
|
+
pmcp sessions broadcast "main moved; sync your worktree before delivering"
|
|
30
|
+
pmcp sessions unbroadcast
|
|
31
|
+
pmcp sessions sweep # drop records whose process is gone
|
|
32
|
+
```
|
|
33
|
+
|
|
34
|
+
While paused, every other session's edits and mutating commands are refused; reading and
|
|
35
|
+
planning continue. A broadcast reaches each running session once, as context. `--by <name>`
|
|
36
|
+
names who pauses or broadcasts; that session is exempt, and without it the sender is
|
|
37
|
+
`operator`.
|
|
38
|
+
|
|
39
|
+
## Send a message to one session
|
|
40
|
+
|
|
41
|
+
With `[sessions.mailbox]` declared, address a session by id, alias, role or linked worktree:
|
|
42
|
+
|
|
43
|
+
```sh
|
|
44
|
+
pmcp sessions send --to alias:reviewer --subject review "Please check the config change"
|
|
45
|
+
pmcp sessions send --to worktree:.claude/worktrees/docs --wake "Rebase onto main"
|
|
46
|
+
pmcp sessions inbox
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
`--wake` also starts a turn in an idle recipient where the runtime allows it (Claude Code,
|
|
50
|
+
opencode). This mailbox is for sessions of one repository; the [local mailbox](mailbox.md)
|
|
51
|
+
serves actors with their own credentials.
|
|
52
|
+
|
|
53
|
+
## Keep agents out of each other's way
|
|
54
|
+
|
|
55
|
+
- **Leases.** `[sessions.leases.<name>]` names a file two sessions must not change at once,
|
|
56
|
+
such as a lockfile. While a delivery that touches it is in progress, the listed commands
|
|
57
|
+
wait.
|
|
58
|
+
- **Linked worktrees.** `pmcp git worktree create <alias>` gives each agent its own checkout;
|
|
59
|
+
an edit left in the shared main checkout blocks syncing it for everyone.
|
|
60
|
+
- **One delivery path.** With `[git.mainline.deliver]`, `pmcp git deliver` replays, tests and
|
|
61
|
+
pushes one delivery at a time, and a direct `git push` is refused.
|
|
62
|
+
|
|
63
|
+
The [Git workflow](git-workflow.md) page covers worktrees, delivery
|
|
64
|
+
and sync. Agents learn the same rules from the pmcp-sessions-and-git skill in the pmcp plugin.
|
package/docs/skills.md
CHANGED
|
@@ -62,51 +62,10 @@ are left out of `skill_catalog` and `skill_find` unless `kind` asks for them
|
|
|
62
62
|
(`agent`, `hook`, `mcp`, or `any`); `skill_describe`, `skill_read` and
|
|
63
63
|
`skill_call` work on every kind.
|
|
64
64
|
|
|
65
|
-
##
|
|
66
|
-
|
|
67
|
-
|
|
68
|
-
|
|
69
|
-
major is a separate selectable plugin. The PMCP bridge has its own `pmcp` plugin.
|
|
70
|
-
The website's `docs/skills/` files are generated downloads from those sources;
|
|
71
|
-
existing URLs and immutable archive bytes remain available.
|
|
72
|
-
|
|
73
|
-
| Tool | Native distribution |
|
|
74
|
-
| --------------- | -------------------------------------------------------------------- |
|
|
75
|
-
| Claude Code | `.claude-plugin/marketplace.json` and plugin manifests |
|
|
76
|
-
| Codex | `.agents/plugins/marketplace.json` and portable `plugin.json` |
|
|
77
|
-
| Grok Build | Claude-compatible marketplace and plugin manifests |
|
|
78
|
-
| Gemini CLI | `gemini-extension.json`; selected CLI exports are extensions |
|
|
79
|
-
| Antigravity CLI | Selected CLI export with its own `plugin.json` and `mcp_config.json` |
|
|
80
|
-
|
|
81
|
-
For native marketplace commands, follow the [README](../README.md).
|
|
82
|
-
Gemini and Antigravity need their own package formats for selected library plugins;
|
|
83
|
-
do not assume that identically named manifest files accept the same schema.
|
|
84
|
-
Since 0.14.0, `pmcp marketplace export <plugin> --runtime <tool>
|
|
85
|
-
--output <new-directory>` materializes a selected package without altering native
|
|
86
|
-
settings or installing it. Use the native manager to review and install that folder.
|
|
87
|
-
Existing export destinations are preserved.
|
|
88
|
-
|
|
89
|
-
The built-in catalog is available without remote fetching.
|
|
90
|
-
`--no-builtin` or `[catalog] builtin = false` opts out; library APIs continue to
|
|
91
|
-
read explicitly supplied catalog roots. `--marketplace <directory>` reads installed
|
|
92
|
-
Claude, Codex and Grok local descriptors, rejects path escapes and does not fetch
|
|
93
|
-
remote plugin sources. Add a remote marketplace with its native manager first.
|
|
94
|
-
|
|
95
|
-
Public npm skill installation uses the bundled catalog, a matching installed
|
|
96
|
-
dependency version and immutable free archive URLs. It verifies archive integrity,
|
|
97
|
-
content-only metadata, instruction digests and installed file bytes. npm, Bun or pnpm
|
|
98
|
-
changes the project and lockfile only after confirmation, with scripts disabled.
|
|
99
|
-
`--provider hosted` remains a separate service path with its own access policy.
|
|
100
|
-
Native plugin installation does not automatically version-match dependencies:
|
|
101
|
-
select the appropriate major yourself. Non-npm library instructions remain manual.
|
|
102
|
-
|
|
103
|
-
## Manually selected Python, Rust and Go library skills
|
|
104
|
-
|
|
105
|
-
Public Pydantic, serde_json and Google UUID instructions are free to read and
|
|
106
|
-
copy into a local collection. Register that collection explicitly; these pilots
|
|
107
|
-
are not automatically matched from PyPI, Cargo or Go dependencies. Follow the
|
|
108
|
-
[manual library skills guide](manual-library-skills.md) for download paths and
|
|
109
|
-
the existing CLI configuration workflow.
|
|
65
|
+
## Library skills
|
|
66
|
+
|
|
67
|
+
Free instructions for public libraries, as native plugins, npm skill packages or (Python, Rust,
|
|
68
|
+
Go) a local collection: [Library skills](library-skills.md).
|
|
110
69
|
|
|
111
70
|
## MCP Skills extension
|
|
112
71
|
|
package/docs/terminal-harness.md
CHANGED
|
@@ -2,14 +2,26 @@
|
|
|
2
2
|
|
|
3
3
|
Use `pmcp harness` to manage a main runtime and its workers through a local CLI.
|
|
4
4
|
Each runtime keeps its own conversation interface, OAuth login, folder trust and
|
|
5
|
-
tool permissions.
|
|
6
|
-
|
|
5
|
+
tool permissions. The one exception is a session pmcp-pty hosts from a
|
|
6
|
+
`[host]` you approved: pmcp-pty may choose the tool-dialog options its
|
|
7
|
+
`[[host.answers]]` list, and never login, auth, trust or hook-review dialogs
|
|
8
|
+
(see [Sessions pmcp-pty hosts](#sessions-pmcp-pty-hosts)). PMCP manages owned
|
|
9
|
+
terminal processes, observations and explicit input delivery. These controls are available from version 0.12.0;
|
|
7
10
|
check your installed release's `pmcp harness --help` before using them.
|
|
8
11
|
|
|
9
|
-
The host
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
12
|
+
The host needs Linux or macOS and pmcp-pty (`crates/pmcp-pty`; set
|
|
13
|
+
PMCP_PTY_BIN to it or put it on PATH). Native executables must be on PATH. Each
|
|
14
|
+
group has its own pmcp-pty daemon on the group's socket: it owns every session's
|
|
15
|
+
PTY, reads its screen through a per-runtime profile and takes input only with
|
|
16
|
+
the session's identity and, while one is held, its lease. On Linux a working user
|
|
17
|
+
systemd manager also caps each session in its own scope inside the group's slice;
|
|
18
|
+
macOS has no equivalent, so sessions run uncapped there while the session count
|
|
19
|
+
still holds. Controlled executable fixtures do not qualify every vendor's prompt
|
|
20
|
+
state, automatic wake, authentication refresh or native children.
|
|
21
|
+
|
|
22
|
+
Groups created by releases before pmcp-pty ran their sessions in tmux. They are
|
|
23
|
+
not migrated: stop and clean them up with the older pmcp release that created
|
|
24
|
+
them, then create a new group.
|
|
13
25
|
|
|
14
26
|
## Check the host
|
|
15
27
|
|
|
@@ -24,17 +36,19 @@ provider feature. Use `pmcp doctor` separately for project configuration checks.
|
|
|
24
36
|
|
|
25
37
|
Group creation checks required tools and contacts the user manager before it
|
|
26
38
|
writes group state. Missing tools return native_host_tool_unavailable followed
|
|
27
|
-
by the tool name
|
|
39
|
+
by the tool name (pmcp-pty, and on Linux systemctl or systemd-run); an
|
|
40
|
+
unreachable manager returns native_user_manager_unavailable.
|
|
28
41
|
The doctor report lists prerequisites and does not certify cgroup delegation.
|
|
29
42
|
An ordinary isolated Docker container usually lacks this user manager and a
|
|
30
43
|
writable delegated cgroup subtree. Container resource limits alone do not
|
|
31
|
-
qualify the native session controls;
|
|
44
|
+
qualify the native session controls; they need the Linux or macOS host itself.
|
|
32
45
|
|
|
33
46
|
## Choose native or Docker execution
|
|
34
47
|
|
|
35
|
-
The default native profile starts executables on the Linux
|
|
36
|
-
Docker profile keeps the same host-side
|
|
37
|
-
each native executable runs in its own bounded
|
|
48
|
+
The default native profile starts executables on the host, Linux or macOS. The
|
|
49
|
+
optional Docker profile needs Linux: it keeps the same host-side pmcp-pty and
|
|
50
|
+
user-systemd controller, while each native executable runs in its own bounded
|
|
51
|
+
container. Docker does not
|
|
38
52
|
replace the host prerequisites above. Only a local Docker Engine is supported.
|
|
39
53
|
|
|
40
54
|
Prepare an image locally with your runtime installed. PMCP requires its exact
|
|
@@ -68,7 +82,7 @@ permission bypass. Docker access itself is a privileged host capability.
|
|
|
68
82
|
|
|
69
83
|
The session `memoryMb` reserves both runtime memory and 64 MiB for its host
|
|
70
84
|
connection. Its Docker memory limit is therefore 64 MiB smaller. Leave additional
|
|
71
|
-
headroom in the group budget for its controller and
|
|
85
|
+
headroom in the group budget for its controller and pmcp-pty daemon.
|
|
72
86
|
Session receipts include the owned container identity only for Docker execution.
|
|
73
87
|
Unknown or changed container identity blocks cleanup and admission.
|
|
74
88
|
|
|
@@ -89,10 +103,10 @@ host proxy rejects private addresses and undeclared destinations. The declared
|
|
|
89
103
|
Node executable must exist inside the image. PMCP stages a digest-checked opaque
|
|
90
104
|
bridge and provides proxy environment variables to the native process. It does
|
|
91
105
|
not intercept TLS or interpret OAuth. A runtime that ignores proxy variables
|
|
92
|
-
cannot reach the provider through this profile.
|
|
93
|
-
|
|
94
|
-
|
|
95
|
-
|
|
106
|
+
cannot reach the provider through this profile. What has been measured through
|
|
107
|
+
it is in [Compatibility](compatibility.md#installation-and-packaging); these two
|
|
108
|
+
hosts are an observed test scope, not a promise that all future Codex features
|
|
109
|
+
use only them.
|
|
96
110
|
|
|
97
111
|
### Keep authenticated roles independent
|
|
98
112
|
|
|
@@ -153,8 +167,9 @@ pmcp harness group list
|
|
|
153
167
|
|
|
154
168
|
The JSON receipt provides the private groupFile and generation. Set GROUP_FILE
|
|
155
169
|
and GENERATION to those values for the examples below. Group state lives below
|
|
156
|
-
XDG_STATE_HOME/pmcp/harness, or ~/.local/state/pmcp/harness.
|
|
157
|
-
|
|
170
|
+
XDG_STATE_HOME/pmcp/harness, or ~/.local/state/pmcp/harness. pmcp keeps the group
|
|
171
|
+
socket path within 100 bytes, below the 104 bytes macOS and 108 bytes Linux allow for a
|
|
172
|
+
Unix socket path, so one state root works on both; an unusually long one is refused.
|
|
158
173
|
|
|
159
174
|
Save `main-spec.json`:
|
|
160
175
|
|
|
@@ -199,7 +214,7 @@ pmcp harness session read --group-file "$GROUP_FILE" --session "$SESSION"
|
|
|
199
214
|
pmcp harness attach open --group-file "$GROUP_FILE" --session "$SESSION"
|
|
200
215
|
```
|
|
201
216
|
|
|
202
|
-
Attachment is read-only by default. Detach with
|
|
217
|
+
Attachment is read-only by default. Detach with Ctrl-\ pressed twice, or use
|
|
203
218
|
attach detach with the target session and current generation. Detach preserves
|
|
204
219
|
the runtime. Reading returns terminal text and does not infer model readiness.
|
|
205
220
|
|
|
@@ -215,18 +230,13 @@ pmcp harness session read --group-file "$GROUP_FILE" --session "$SESSION" --inpu
|
|
|
215
230
|
|
|
216
231
|
lines accepts 1–2000 and maxBytes accepts 1–65536. Defaults remain 100 lines and
|
|
217
232
|
16384 bytes. A bounded result reports truncated when it omits earlier content.
|
|
218
|
-
|
|
219
|
-
|
|
220
|
-
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
|
|
225
|
-
one prefix to the inner layer. Ctrl-b then [ opens the outer copy mode, while
|
|
226
|
-
Ctrl-b, Ctrl-b, d detaches the inner connection. Outer history is the rendered
|
|
227
|
-
wrapper screen; session read retrieves the owned runtime's history.
|
|
228
|
-
PMCP does not change the outer tmux configuration. Other terminal mouse and
|
|
229
|
-
trackpad settings require their own qualification.
|
|
233
|
+
Lines come from the session's recent output with terminal escapes removed;
|
|
234
|
+
alternate: true returns the screen as it is now instead. Both read the owned
|
|
235
|
+
session only, separate from a surrounding terminal's older shell output.
|
|
236
|
+
|
|
237
|
+
A read-only attachment drops every keystroke; use session read for history
|
|
238
|
+
without acquiring control. Ctrl-\ followed by any other key is passed through,
|
|
239
|
+
so a nested terminal multiplexer keeps its own prefix.
|
|
230
240
|
|
|
231
241
|
For bounded polling, session watch also takes an input file containing count
|
|
232
242
|
(1–10) and intervalMs (100–2000). It returns snapshots rather than an endless
|
|
@@ -241,8 +251,10 @@ pmcp harness attach open --group-file "$GROUP_FILE" --generation "$GENERATION" -
|
|
|
241
251
|
|
|
242
252
|
Set LEASE_FILE to the acquire receipt's private credential path. A writable
|
|
243
253
|
attachment renews its 60-second lease and releases it after detach. Failed
|
|
244
|
-
renewal disconnects the client. It does not stop the runtime.
|
|
245
|
-
|
|
254
|
+
renewal disconnects the client. It does not stop the runtime. pmcp-pty holds
|
|
255
|
+
the same lease token, so while it is held it refuses a writable attachment or
|
|
256
|
+
input without it, and a person typing in an attachment wins over program input
|
|
257
|
+
for five seconds after the last keystroke.
|
|
246
258
|
|
|
247
259
|
## Deliver input explicitly
|
|
248
260
|
|
|
@@ -256,7 +268,7 @@ pmcp harness control release --group-file "$GROUP_FILE" --generation "$GENERATIO
|
|
|
256
268
|
```
|
|
257
269
|
|
|
258
270
|
Write and Enter submission are separate operations. Newlines, tabs, terminal
|
|
259
|
-
control characters and input above 16 KiB are refused.
|
|
271
|
+
control characters and input above 16 KiB are refused. Bracketed paste alone
|
|
260
272
|
cannot guarantee safe multiline delivery in a native approval menu.
|
|
261
273
|
|
|
262
274
|
Inspect the native screen before writing or submitting. A control lease identifies
|
|
@@ -289,14 +301,50 @@ PMCP does not create another message engine or automatically type a wake prompt
|
|
|
289
301
|
into a native menu. Follow the [mailbox guide](mailbox.md) for actor credentials
|
|
290
302
|
and launcher-bound runtime attachments.
|
|
291
303
|
There is no automatic delivery loop. Native readiness and approval stay with
|
|
292
|
-
|
|
304
|
+
you and the runtime; an input receipt does not establish prompt readiness.
|
|
305
|
+
|
|
306
|
+
### Sessions pmcp-pty hosts
|
|
307
|
+
|
|
308
|
+
`[host]` in pmcp.toml lists long-running sessions for one shared pmcp-pty host
|
|
309
|
+
outside any group (see
|
|
310
|
+
[Sessions pmcp-pty hosts](project-configuration.md#sessions-pmcp-pty-hosts)).
|
|
311
|
+
After `pmcp project` and your own `pmcp harness host approve`:
|
|
312
|
+
|
|
313
|
+
`host up` and `host unit` need Linux with a user systemd manager. On macOS they
|
|
314
|
+
stop with `platform_unsupported`; use `pmcp tui` or a harness group there.
|
|
315
|
+
|
|
316
|
+
- `pmcp harness host up` starts pmcp-pty if its socket (`PMCP_PTY_SOCKET`, else
|
|
317
|
+
`$XDG_RUNTIME_DIR/pmcp-pty.sock`) does not answer, in a transient
|
|
318
|
+
`systemd-run --user --scope` capped at 4G and loading the approved copy with
|
|
319
|
+
`--host`. The binary is `PMCP_PTY_BIN`, else the first `pmcp-pty` on
|
|
320
|
+
`PATH`; without one, `up` stops at once and `pmcp doctor` says so, and a
|
|
321
|
+
start that never answers reports the scope's own output (kept in
|
|
322
|
+
`host-daemon.log` beside the journal). It starts each approved session that
|
|
323
|
+
is not running, labelled
|
|
324
|
+
`pmcp.host=<name>`, and leaves running ones alone. An exited session
|
|
325
|
+
restarts only with `restart = "on-exit"`, up to `max_restarts` since its
|
|
326
|
+
last fresh start; run `up` again to apply it, since nothing watches in the
|
|
327
|
+
background. Each start, restart and stop goes to `host-runs.jsonl` in the
|
|
328
|
+
project's pmcp state directory.
|
|
329
|
+
- `pmcp harness host down` stops the host's sessions (their whole process
|
|
330
|
+
trees) and forgets them, so the next `up` starts them fresh. pmcp-pty and
|
|
331
|
+
its other sessions keep running.
|
|
332
|
+
- `pmcp harness host status` reports the approval: `approved`, `differs` (a
|
|
333
|
+
newer projection waits for approval; the approved one keeps running),
|
|
334
|
+
`unapproved` or `unprojected`.
|
|
335
|
+
- `pmcp harness host unit` prints a systemd user unit that runs pmcp-pty with
|
|
336
|
+
the approved copy. Installing and enabling it is your step; pmcp
|
|
337
|
+
never writes or enables a unit.
|
|
338
|
+
|
|
339
|
+
`up` and `down` use only the approved copy, so a session or answer an agent
|
|
340
|
+
adds to pmcp.toml runs only after you approve it.
|
|
293
341
|
|
|
294
342
|
### A manual request and review workflow
|
|
295
343
|
|
|
296
344
|
Mailbox actor names and harness session roles are separate. Creating a main or
|
|
297
345
|
worker terminal does not register a mailbox actor or give it credentials. Use
|
|
298
|
-
the mailbox guide to initialize the project and register main
|
|
299
|
-
operator actors. Keep their credential files private. The following workflow
|
|
346
|
+
the mailbox guide to initialize the project and register `main`, `worker` and
|
|
347
|
+
`operator` actors. Keep their credential files private. The following workflow
|
|
300
348
|
uses CLI actor files for manual coordination; it does not attach a vendor child
|
|
301
349
|
or automatically configure a runtime's MCP server.
|
|
302
350
|
|
|
@@ -340,8 +388,8 @@ task state machine. A new attempt uses a new request and idempotency key; keep
|
|
|
340
388
|
the previous result in its original thread. Exact send retries reuse their key
|
|
341
389
|
and return the existing message; changed payloads are refused.
|
|
342
390
|
|
|
343
|
-
The main can send its synthesis to operator as a reply to the reviewed result.
|
|
344
|
-
After reading it,
|
|
391
|
+
The main can send its synthesis to `operator` as a reply to the reviewed result.
|
|
392
|
+
After reading it, you may send a separate acceptance reply as `operator`. ACK records
|
|
345
393
|
receipt handling only. Neither result text, ACK nor acceptance automatically
|
|
346
394
|
submits a terminal draft, transfers control or executes a command.
|
|
347
395
|
|
|
@@ -354,15 +402,15 @@ reservations. Expanding grants requires a new group.
|
|
|
354
402
|
|
|
355
403
|
session stop names one owned session. group stop explicitly stops its entire
|
|
356
404
|
owned group and removes runtime budget properties. Both require the current
|
|
357
|
-
generation. They do not target an existing external
|
|
405
|
+
generation. They do not target an existing external terminal session.
|
|
358
406
|
|
|
359
407
|
recovery inspect reports observations, leases, uncertain deliveries and
|
|
360
408
|
unregistered owned sessions. recovery reconcile removes a writer lock only
|
|
361
409
|
after its controller has exited and never resends input. Use recovery
|
|
362
410
|
stop-orphan for a named unregistered session, or recovery replace-main with a
|
|
363
411
|
new main specification after the previous main has stopped. Replacement changes
|
|
364
|
-
the generation and invalidates old control credentials.
|
|
365
|
-
identity fails closed; no session is silently adopted.
|
|
412
|
+
the generation and invalidates old control credentials. An unknown host instance
|
|
413
|
+
or session identity fails closed; no session is silently adopted.
|
|
366
414
|
|
|
367
415
|
Include pending starts explicitly when inspecting a failed launch:
|
|
368
416
|
|
|
@@ -375,7 +423,7 @@ abort-start stops a named incomplete launch and marks any saved group reference
|
|
|
375
423
|
as stopped. It neither adopts the session nor restarts it. A committed session
|
|
376
424
|
uses session stop instead. If the start gate died before recording ownership,
|
|
377
425
|
automatic cleanup is refused and admission remains blocked for administrative
|
|
378
|
-
repair. Keep the private state directory as evidence; do not guess a
|
|
426
|
+
repair. Keep the private state directory as evidence; do not guess a session id
|
|
379
427
|
or resend an uncertain request.
|
|
380
428
|
|
|
381
429
|
## Layout planning
|
|
@@ -384,7 +432,7 @@ or resend an uncertain request.
|
|
|
384
432
|
pmcp harness layout --columns 120 --rows 40
|
|
385
433
|
```
|
|
386
434
|
|
|
387
|
-
This pure command needs no
|
|
435
|
+
This pure command needs no terminal host, provider, project or network. It returns layout
|
|
388
436
|
A at 120 columns and 32 rows or larger: a main pane, worker dock and bottom
|
|
389
437
|
coordination pane. Smaller terminals retain a full-width main. The minimum is
|
|
390
438
|
40 columns by 12 rows; the maximum is 1000 in either dimension.
|