@modootoday/pmcp 0.24.1 → 0.26.0
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 +1 -1
- package/.mcp.json +1 -1
- package/dist/{affected-IPFJM2KD.js → affected-4FILH743.js} +174 -77
- package/dist/{apply-CDJQJAZH.js → apply-HJUCYQDQ.js} +18 -15
- package/dist/{broadcast-VKZY7WSD.js → broadcast-U7ZYOJWE.js} +7 -4
- package/dist/{chunk-GEDRPMBH.js → chunk-2GL5L2G5.js} +2 -2
- package/dist/{chunk-AQM2JZMB.js → chunk-2JUHFM4V.js} +2 -2
- package/dist/{chunk-UKR64U7J.js → chunk-374AZ4J4.js} +2 -2
- package/dist/{chunk-MZ52S4YJ.js → chunk-3JOFDNL4.js} +2 -2
- package/dist/{chunk-264DIB5U.js → chunk-3KISMGVP.js} +4 -4
- package/dist/{chunk-V5PXMLLL.js → chunk-6XE3WW7S.js} +3 -3
- package/dist/{chunk-7CGGDX7X.js → chunk-7FHOSWNQ.js} +2 -2
- package/dist/{chunk-5NQZGNKT.js → chunk-7PBWLYCO.js} +3 -3
- package/dist/{chunk-2GZKA33O.js → chunk-A4P3IIPE.js} +2 -2
- package/dist/{chunk-3O3JZTUU.js → chunk-C7Y2MBCN.js} +3 -3
- package/dist/chunk-D7IDT7OA.js +21 -0
- package/dist/chunk-E272CFPS.js +14 -0
- package/dist/chunk-FLG7VRTC.js +1 -0
- package/dist/{chunk-X3RUXLAV.js → chunk-FXDGW2IH.js} +3 -3
- package/dist/{chunk-DLIO2D7S.js → chunk-GIL3RBRX.js} +27 -20
- package/dist/{chunk-ARXCYFFZ.js → chunk-GQRDEIQA.js} +22 -2
- package/dist/chunk-J43Z4O3G.js +7 -0
- package/dist/chunk-KLIYFD3W.js +32 -0
- package/dist/{chunk-PG62GOPU.js → chunk-KQV2EPAP.js} +2 -2
- package/dist/{chunk-LNKAR3IS.js → chunk-LCPCRZ7N.js} +2 -2
- package/dist/chunk-NQCAKDRY.js +156 -0
- package/dist/{chunk-3SEJNT6F.js → chunk-NQZMGQFG.js} +5 -5
- package/dist/{chunk-DGXZBQCA.js → chunk-OBCBCLS2.js} +7 -7
- package/dist/{chunk-D4FIBB2G.js → chunk-OG2ESRQP.js} +5 -5
- package/dist/{chunk-43MXRTKH.js → chunk-OHCUPXU4.js} +26 -8
- package/dist/chunk-OIKT4SYO.js +42 -0
- package/dist/{chunk-3V37OZQH.js → chunk-PAY6HEEY.js} +2 -2
- package/dist/{chunk-QY2P54Z2.js → chunk-PZ6D3WKD.js} +125 -8
- package/dist/{chunk-MOKZPZZO.js → chunk-Q5BQIRM3.js} +2 -2
- package/dist/{chunk-VYQJPT27.js → chunk-S2FUWBLO.js} +18 -4
- package/dist/{chunk-OGCJO6HQ.js → chunk-TQRLWO4F.js} +2 -2
- package/dist/{chunk-VBWB2T3C.js → chunk-UVPIVSZB.js} +14 -6
- package/dist/{chunk-MHKY6TNF.js → chunk-VN34GLGJ.js} +3 -3
- package/dist/chunk-WUFNKK3U.js +71 -0
- package/dist/{chunk-2ZH77O2D.js → chunk-Y7FYCVUK.js} +646 -103
- package/dist/{chunk-HES44LTA.js → chunk-YJVSN6UN.js} +29 -5
- package/dist/{chunk-EWYLWBKS.js → chunk-YKICVMF7.js} +22 -5
- package/dist/{cli-OV5LSSGE.js → cli-FVUHK2NB.js} +7 -7
- package/dist/{cli-GFDT4YXM.js → cli-ZOY2274X.js} +9 -9
- package/dist/cli.js +40 -6
- package/dist/{completion-QNDCU4MF.js → completion-ZKWGPMEK.js} +6 -5
- package/dist/{diagnostics-TPK3VC5F.js → diagnostics-IM2OPAPL.js} +7 -7
- package/dist/{doctor-K2LADSW2.js → doctor-VZTHEPVC.js} +32 -20
- package/dist/{entry-HFQHKL5L.js → entry-Q4EI4PNO.js} +13 -13
- package/dist/{exec-mcp-I2YGGWY4.js → exec-mcp-AWGUQVT2.js} +15 -12
- package/dist/{harness-BMWGAXCF.js → harness-L4C5XWKR.js} +3 -3
- package/dist/harness-launch-gate.js +5 -5
- package/dist/harness-worker.js +7 -7
- package/dist/{heavy-G6CYQQ7O.js → heavy-OG3UVZNY.js} +327 -131
- package/dist/hook-body.js +664 -161
- package/dist/{hook-spec-Bd24eo2L.d.ts → hook-spec-u7hnz571.d.ts} +10 -0
- package/dist/{hooks-R7AYQXHY.js → hooks-2E6PJJQK.js} +4 -4
- package/dist/{host-PLE2T55E.js → host-OQDBQJB2.js} +8 -8
- package/dist/{host-EUD6GLWV.js → host-RJJGTKWA.js} +20 -65
- package/dist/{host-run-QFNGIDL5.js → host-run-PWCIXJDN.js} +6 -6
- package/dist/http.js +1 -1
- package/dist/{import-mcp-DVKJOEOE.js → import-mcp-2H2NRUCL.js} +14 -11
- package/dist/index.d.ts +2 -2
- package/dist/index.js +18 -15
- package/dist/{init-DKWNL62M.js → init-O2UCU2WT.js} +2 -2
- package/dist/{invoke-U6JTPTXT.js → invoke-SJ3JHRJU.js} +9 -9
- package/dist/{list-YKQFJN3G.js → list-SJVXZGKK.js} +17 -14
- package/dist/{logout-5YSKC46N.js → logout-ROKXWR3T.js} +15 -12
- package/dist/{logs-2JEMSNSG.js → logs-J4W6GFMK.js} +4 -4
- package/dist/{mailbox-5FVFMQ2J.js → mailbox-6MHH6CUA.js} +22 -8
- package/dist/{mainline-D3PSR6AJ.js → mainline-SWZPKA7U.js} +19 -9
- package/dist/{mcp-CHKKXHBB.js → mcp-U7MVFAB4.js} +2 -2
- package/dist/owners-MPI22SFU.js +63 -0
- package/dist/{pause-CMZOIHTJ.js → pause-3IMVYXQQ.js} +7 -4
- package/dist/project/hook-adapter.d.ts +1 -1
- package/dist/{project-QEYXISHC.js → project-MGUYHUF7.js} +4 -4
- package/dist/{report-UB7MXAUB.js → report-MWXB5XKE.js} +5 -5
- package/dist/{resume-PAKIT4TT.js → resume-7LCSV4X3.js} +7 -4
- package/dist/{run-HKMYYEZJ.js → run-DDWLS6FY.js} +14 -11
- package/dist/{run-FYKDIW4C.js → run-TBO5JO4Y.js} +4 -4
- package/dist/{serve-QZNG5UUV.js → serve-RBQYB3FP.js} +3 -3
- package/dist/{setup-GRWLDBVB.js → setup-7JHWLV7K.js} +6 -4
- package/dist/{smoke-6X6IXQIQ.js → smoke-GZECLXOJ.js} +3 -3
- package/dist/{start-login-4GPM32RA.js → start-login-SOTNDUP6.js} +15 -12
- package/dist/{status-55CD352M.js → status-EBIUQIGY.js} +35 -30
- package/dist/{status-4PYPTYUB.js → status-QFMN7IUG.js} +8 -5
- package/dist/{status-W6SCF2GF.js → status-TSTOFNZU.js} +15 -12
- package/dist/stdio.js +2 -2
- package/dist/{sweep-VURZU6DI.js → sweep-BS7HVSNP.js} +7 -4
- package/dist/{test-XYEMYZ2P.js → test-4PZHHWOQ.js} +28 -16
- package/dist/{tui-FXSWN2PV.js → tui-QD2LMXHV.js} +4 -4
- package/dist/{unbroadcast-7AMLURCG.js → unbroadcast-GRGX3F6T.js} +7 -4
- package/dist/{worker-Q4I4EIAJ.js → worker-SPJ4HFWV.js} +11 -11
- package/dist/{worktree-list-2HV6ODBS.js → worktree-list-WZC75NLF.js} +8 -9
- package/dist/{worktree-sync-MUVKK2CV.js → worktree-sync-BQZD4J73.js} +5 -2
- package/docs/commands.md +18 -7
- package/docs/git-workflow.md +40 -5
- package/docs/glossary.md +1 -1
- package/docs/hooks.md +75 -16
- package/docs/project-configuration.md +136 -40
- package/docs/sessions.md +9 -2
- package/docs/upgrading.md +71 -0
- package/gemini-extension.json +2 -2
- package/mcp.json +1 -1
- package/package.json +5 -5
- package/plugin.json +1 -1
- package/plugins/pmcp/.claude-plugin/plugin.json +1 -1
- 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/plugin.json +1 -1
- package/dist/chunk-65H4PN33.js +0 -7
- package/dist/chunk-7TD53M7L.js +0 -13
- package/dist/chunk-FQLCD4HU.js +0 -24
|
@@ -58,10 +58,12 @@ ignored.
|
|
|
58
58
|
| `[marketplaces.<name>]` | [Marketplaces](#marketplaces) |
|
|
59
59
|
| `[targets]`, `[skills.<name>]`, `[agents.<name>.<tool>]`, `[rules.packages]` | [Native files for each agent tool](#native-files-for-each-agent-tool) |
|
|
60
60
|
| `[mcp.<alias>]` | [Unified project MCP configuration](#unified-project-mcp-configuration) |
|
|
61
|
-
| `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[hooks.checks.*]`, `[hooks.failure]`, `[hooks.report]`, `[hooks.test]`
|
|
61
|
+
| `[hooks]`, `[hooks.guards.*]`, `[[hooks.guards.custom]]`, `[[hooks.guards.external]]`, `[hooks.checks.*]`, `[hooks.failure]`, `[hooks.report]`, `[hooks.test]` | [Hooks](hooks.md) |
|
|
62
62
|
| `[budget]` | [Budget](#budget) |
|
|
63
|
+
| `[budgets]` | [Budgets](#budgets) |
|
|
64
|
+
| `[[owners]]` | [Owners](#owners) |
|
|
63
65
|
| `[[hooks.shell]]`, `[[hooks.edit]]` | [Deprecated shell guards](hooks.md#deprecated-shell-guards) |
|
|
64
|
-
| `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]`
|
|
66
|
+
| `[sessions]`, `[sessions.registry]`, `[sessions.pause]`, `[sessions.broadcast]`, `[sessions.mailbox]`, `[sessions.leases.<name>]`, `[sessions.roles.<name>]`, `[sessions.operator]` | [Sessions](#sessions) |
|
|
65
67
|
| `[git]`, `[git.shared_checkout]`, `[git.worktrees]`, `[git.worktrees.sync]`, `[git.mainline]`, `[git.mainline.gate]`, `[git.mainline.deliver]`, `[git.mainline.sync]`, `[git.submodules]` | [Git workflow](git-workflow.md) |
|
|
66
68
|
| `[logging]`, `[logging.components]` | [Logging](#logging) |
|
|
67
69
|
| `[permissions.claude]` | [Claude permission rules](#claude-permission-rules) |
|
|
@@ -276,8 +278,9 @@ max_io = 8
|
|
|
276
278
|
budget = 4
|
|
277
279
|
hold_warn = 1800
|
|
278
280
|
hold_max = 3600
|
|
279
|
-
heavy = [
|
|
281
|
+
heavy = ["default", ["make", "all"]]
|
|
280
282
|
guard = "deny"
|
|
283
|
+
skip_reasons = ["ci"]
|
|
281
284
|
|
|
282
285
|
[host.lease.lanes]
|
|
283
286
|
interactive = 2
|
|
@@ -292,38 +295,40 @@ max_wait = 2700
|
|
|
292
295
|
load_grace = 600
|
|
293
296
|
```
|
|
294
297
|
|
|
295
|
-
| Key | Type
|
|
296
|
-
| ------------------- |
|
|
297
|
-
| `enabled` | boolean
|
|
298
|
-
| `dir` | path
|
|
299
|
-
| `budget` | integer
|
|
300
|
-
| `lanes.<lane>` | integer
|
|
301
|
-
| `weights.<lane>` | integer
|
|
302
|
-
| `commands` | tables
|
|
303
|
-
| `tiny` | argv lists
|
|
304
|
-
| `per_session` | integer
|
|
305
|
-
| `marker_env` | name
|
|
306
|
-
| `legacy_marker_env` | name
|
|
307
|
-
| `legacy_skip_env` | name
|
|
308
|
-
| `skip_always` | list of reasons
|
|
309
|
-
| `
|
|
310
|
-
| `
|
|
311
|
-
| `
|
|
312
|
-
| `
|
|
313
|
-
| `
|
|
314
|
-
| `
|
|
315
|
-
| `
|
|
316
|
-
| `
|
|
317
|
-
| `
|
|
318
|
-
| `
|
|
319
|
-
| `
|
|
320
|
-
| `
|
|
321
|
-
| `
|
|
322
|
-
| `
|
|
323
|
-
| `io.
|
|
324
|
-
| `io.
|
|
325
|
-
| `
|
|
326
|
-
| `
|
|
298
|
+
| Key | Type | Default | Meaning |
|
|
299
|
+
| ------------------- | -------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
300
|
+
| `enabled` | boolean | `true` | `false` runs every `pmcp heavy` command at once, gates without the lease and turns the guard off. |
|
|
301
|
+
| `dir` | path | `~/.cache/pmcp/host` | Where the lock file (`heavy.lock`), the admission lock, the `running/` and `waiters/` records, the holder record and `heavy.log` live. Every tool sharing the lease names the same directory. |
|
|
302
|
+
| `budget` | integer | `4` | The most weight that runs at once. `1` is one job at a time. |
|
|
303
|
+
| `lanes.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 1 | How many jobs of a lane run at once; `0` closes the lane. |
|
|
304
|
+
| `weights.<lane>` | integer | gate 1, hook 1, interactive 2, bulk 3 | A job's weight when neither `--weight` nor a `commands` entry names one. A weight above the budget counts as the budget. |
|
|
305
|
+
| `commands` | tables | none | `argv` prefix, `lane` and `weight` for commands run without `--lane` or `--weight`; the first match wins. |
|
|
306
|
+
| `tiny` | argv lists | none | Commands so short (a few seconds) that they take no slot and no budget (weight 0, also `--weight 0`); only the hard ceiling holds them back, and the log still records them. |
|
|
307
|
+
| `per_session` | integer | `1` | How many jobs one agent session may have queued in the interactive lane, and in the bulk lane; the next one waits outside the queue holding no place. `0` is no cap. Gate and hook are exempt. |
|
|
308
|
+
| `marker_env` | name | `PMCP_HEAVY_LEASE` | Set to the job's pid for the leased command; a nested `pmcp heavy` whose marker names a running job runs at once. |
|
|
309
|
+
| `legacy_marker_env` | name | none | A second marker, set and honoured like `marker_env`, for a shell wrapper that shares `dir`. |
|
|
310
|
+
| `legacy_skip_env` | name | none | A second skip variable, honoured like `PMCP_HEAVY_DISABLE`, and set for the leased command so a nested shell wrapper runs at once. |
|
|
311
|
+
| `skip_always` | list of reasons | `[]` | Skip reasons honoured even for a bulk job, for callers that must never wait on the lease (a commit hook). They are allowed skip reasons too. |
|
|
312
|
+
| `skip_reasons` | list of reasons | `[]` | The further reasons `PMCP_HEAVY_DISABLE` may carry for an ordinary command, beside the built-in `nested` and `operator`. Lower-case words (`a-z`, digits, `-`, `_`, `.`, `:`). |
|
|
313
|
+
| `max_load` | number | the CPU count | A job starts only while the 1-minute load average is below this. |
|
|
314
|
+
| `max_io` | number | `8` | And while IO pressure (`some`, the `io_window` average) is below this. A host without pressure files checks load only; one without a load average checks neither. |
|
|
315
|
+
| `io_window` | string | `avg60` | Which pressure average the check reads: `avg10` follows spikes, `avg60` and `avg300` smooth them so the queue does not stall on a burst. |
|
|
316
|
+
| `max_wait` | seconds | `3600` | How long the `default` profile waits; then nothing runs and the exit is 75. |
|
|
317
|
+
| `load_grace` | seconds | `900` | After this long waiting on the host, a job may start into moderate overload, but only while no leased job runs, so a grace never starts two jobs together. `0` is no grace. |
|
|
318
|
+
| `hard_factor` | number | `2` | Never start, grace or not, while load or IO is at this many times its limit; such a job waits until `max_wait`, then exits 75. |
|
|
319
|
+
| `hold_warn` | seconds | `1800` | A job running past this prints one warning, and `pmcp heavy status` marks it. |
|
|
320
|
+
| `hold_max` | seconds | none | `pmcp heavy status` flags a job past this as over the limit. Nothing is killed. |
|
|
321
|
+
| `memory_max` | size | none | Runs each command in `systemd-run --user --scope -p MemoryMax=<size> -p MemorySwapMax=0` where that is available, so a runaway job is killed alone. Without a reachable user manager (no `XDG_RUNTIME_DIR`, or no manager socket in it, as under `env -i` or cron) the command runs without the scope and one line on stderr says why; if `systemd-run` still cannot reach the bus, the command runs once more without it. A missing scope never fails the command. |
|
|
322
|
+
| `heartbeat`, `poll` | seconds | `60`, `15` | How often a waiter prints that it is still waiting, and how often the host is reread. |
|
|
323
|
+
| `profiles.<name>` | table | gate 2700/600, hook 900/30 | `max_wait`, `load_grace` and `memory_max` for `pmcp heavy --profile <name>`. The `gate` and `hook` profiles also choose their lane. Any other profile starts from the top-level values. |
|
|
324
|
+
| `heavy` | argv lists, or `"default"` | `"default"` with the table, none without | The commands the `host.lease` guard expects under the lease, as argv prefixes. `"default"`, alone or as an item of the list, names pmcp's preset: `install` (and `i`, `ci`), `test`, `build` and `typecheck` for npm, pnpm, yarn and bun (`<manager> run <script>` too), and `cargo build`, `test` and `check`. An empty list turns the guard off. |
|
|
325
|
+
| `guard` | string | `observe` | The `host.lease` guard's mode: `observe` logs what it would have refused (at info, so `pmcp hooks report --switch-check host.lease` reads it at the default log level), `warn` tells the agent, `deny` refuses with the command to run instead (`pmcp heavy -- <command>`), `off`. A command already wrapped passes. Run a week in `observe`, read the report, then set `deny`. |
|
|
326
|
+
| `io.enabled` | `"auto"` or boolean | `"auto"` | Each leased job runs in its own `systemd-run --user` scope and gets its lane's `io.weight` where the cgroup v2 io controller reaches the user manager; elsewhere nothing changes. `true` also says when it could not; `false` never. |
|
|
327
|
+
| `io.weights.<lane>` | integer | gate 500, hook 300, interactive 100, bulk 25 | The scope's `io.weight` per lane (1 to 10000). |
|
|
328
|
+
| `io.max.<lane>` | string | none | An `io.max` line for the lane's scopes, such as `"259:0 wbps=50000000"`; the device is this host's to name. |
|
|
329
|
+
| `settle_window` | seconds | `60` | After a leased job ends, its own leftover IO may hold the queue only this long: then a waiter starts on a moderately busy host (below `hard_factor`). `0` turns it off. |
|
|
330
|
+
| `usage_cap` | bytes | `5000000` | `usage.jsonl` (one record per run) moves to `usage.jsonl.1` past this size. |
|
|
331
|
+
| `job_log_bytes` | bytes | `4194304` | Each job's stdout and stderr are kept in its ticket (`<dir>/tickets/<id>/log`), moving to `log.1` past this size; `pmcp heavy result <id> --log` prints them. `0` keeps nothing for blocking runs, which then write to the terminal directly; a submitted job always keeps its output. |
|
|
327
332
|
|
|
328
333
|
Lanes, in the order a short budget goes to them: `gate` (a land's gate),
|
|
329
334
|
`hook` (commit-hook work, a short slot that skips the host wait unless the host
|
|
@@ -337,7 +342,7 @@ on every admission, so running weight never exceeds the budget and a crashed
|
|
|
337
342
|
job frees its share.
|
|
338
343
|
|
|
339
344
|
`pmcp heavy --now --reason <text>` (or `PMCP_HEAVY_NOW=<reason>` in a script) is
|
|
340
|
-
the emergency bypass: the command starts at once, outside the lanes, the budget
|
|
345
|
+
the operator's emergency bypass ([the operator](#the-operator)): the command starts at once, outside the lanes, the budget
|
|
341
346
|
and the host check, and never exits 75, but it needs a reason, is logged as a
|
|
342
347
|
`bypass` line, shows as `bypass running` in status and counts its weight, so the
|
|
343
348
|
other jobs' admission sees its load. It is not the off switch below.
|
|
@@ -355,7 +360,13 @@ the configured ones.
|
|
|
355
360
|
`PMCP_HEAVY_DISABLE=<reason>` (or the `legacy_skip_env` variable) skips the
|
|
356
361
|
lease for an ordinary command: `pmcp heavy` runs it at once, logs the reason,
|
|
357
362
|
and keeps it as `skip` in the command's usage record, and the guard lets a
|
|
358
|
-
command that sets it pass. The
|
|
363
|
+
command that sets it pass. The reason is one of a closed set: `nested`, which
|
|
364
|
+
pmcp sets itself for a wrapper inside a leased job and honours only while a
|
|
365
|
+
leased job encloses the command; `operator`, honoured only for
|
|
366
|
+
[the operator](#the-operator); and the names in `skip_reasons` or `skip_always`.
|
|
367
|
+
Any other reason runs nothing: `pmcp heavy` exits 2 naming the allowed reasons,
|
|
368
|
+
logs a `skip-invalid` line and records `skip_invalid`, so the share of skipped
|
|
369
|
+
runs reads by reason in `pmcp heavy stats`. The skip is bounded: a bulk job (an install, a
|
|
359
370
|
whole test suite, a full build), put in the `bulk` lane by `--lane bulk` or by
|
|
360
371
|
a `commands` entry, still queues in that lane, with a line on standard error
|
|
361
372
|
saying the skip was not honoured and `skip_refused` in its usage record. The
|
|
@@ -373,6 +384,7 @@ that must never wait on the lease, such as a commit hook:
|
|
|
373
384
|
```toml
|
|
374
385
|
[host.lease]
|
|
375
386
|
skip_always = ["git-hook"] # PMCP_HEAVY_DISABLE=git-hook runs even a bulk job at once
|
|
387
|
+
skip_reasons = ["ci"] # PMCP_HEAVY_DISABLE=ci runs an ordinary command at once
|
|
376
388
|
```
|
|
377
389
|
|
|
378
390
|
The files extend those of a shell wrapper that takes the same lock with
|
|
@@ -628,6 +640,34 @@ lives in one directory shared by every checkout of the repository.
|
|
|
628
640
|
These tables have no `mode`, except pause. Without `[sessions.registry]` no
|
|
629
641
|
session is recorded, and `[ui.claude]` refuses to project.
|
|
630
642
|
|
|
643
|
+
### The operator
|
|
644
|
+
|
|
645
|
+
The operator is you: the person who governs the agent sessions. A few verbs are yours alone,
|
|
646
|
+
because an agent running them would govern the others: `pmcp sessions pause` and `resume`,
|
|
647
|
+
`pmcp heavy --now` (and `PMCP_HEAVY_NOW`), `pmcp heavy promote --now`,
|
|
648
|
+
`pmcp heavy cancel --force` on another session's job, and `pmcp git deliver --during-pause`.
|
|
649
|
+
Signing a broadcast or a message as `operator` is yours too. `[sessions.operator]` says how
|
|
650
|
+
pmcp recognises you:
|
|
651
|
+
|
|
652
|
+
| Key | Type | Default | Meaning |
|
|
653
|
+
| ------------ | ------ | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
654
|
+
| `via` | string | `"tty"` | `"tty"`: an interactive terminal (standard input) with no agent runtime among the command's parent processes and no agent's environment markers. `"token"`: `PMCP_OPERATOR_TOKEN` equals the contents of `token_file`, wherever the command runs (a script, cron). |
|
|
655
|
+
| `token_file` | path | none | With `via = "token"`: absolute or `~/…`, outside the project, readable by its owner only (mode 600); pmcp refuses a file others can read. |
|
|
656
|
+
|
|
657
|
+
```toml
|
|
658
|
+
[sessions.operator]
|
|
659
|
+
via = "token"
|
|
660
|
+
token_file = "~/.config/pmcp/operator-token"
|
|
661
|
+
```
|
|
662
|
+
|
|
663
|
+
Run from an agent session, an operator verb exits 1 with
|
|
664
|
+
`<verb> is the operator's to run: <why>. Ask the operator to run it from their own terminal`,
|
|
665
|
+
and changes nothing; the agent relays the request to you. With any session feature declared,
|
|
666
|
+
the `pmcp.operator_verbs` guard ([Hooks](hooks.md)) also refuses these command lines in the
|
|
667
|
+
agent's runtime, before they run. Every session runs as the same user, so this stops
|
|
668
|
+
instructed agents and accidents rather than a determined process: for a hard boundary run the
|
|
669
|
+
agents under another user, where a token file only you can read keeps them out.
|
|
670
|
+
|
|
631
671
|
### `[sessions.mailbox]`
|
|
632
672
|
|
|
633
673
|
Addressed messages between sessions, and between you and them. A missing table leaves
|
|
@@ -733,6 +773,31 @@ are still written, so `pmcp sessions status`, the session list and the
|
|
|
733
773
|
Claude Code session panes read broadcasts as before. `unbroadcast` withdraws those
|
|
734
774
|
messages too.
|
|
735
775
|
|
|
776
|
+
## Owners
|
|
777
|
+
|
|
778
|
+
`[[owners]]` says who looks after a path, so an agent that edits or delivers it
|
|
779
|
+
is told whom to tell. It only informs and never refuses.
|
|
780
|
+
|
|
781
|
+
| Key | Type | Default | Meaning |
|
|
782
|
+
| ------- | --------- | -------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
783
|
+
| `paths` | glob list | required | Globs relative to the directory holding `pmcp.toml`, as in `[budget] forbid_paths`; a directory covers what is below it. |
|
|
784
|
+
| `owner` | string | required | The person, team or session that looks after them. |
|
|
785
|
+
| `note` | string | none | What to do, such as whom to ask first. |
|
|
786
|
+
| `mode` | string | `"warn"` | `warn` tells the agent; `observe` only logs that the path was edited. |
|
|
787
|
+
|
|
788
|
+
With `warn`, an agent that edits a matching file gets one line of context after
|
|
789
|
+
the edit, `pmcp owners: <path> belongs to <owner>: <note>`, once per owner per
|
|
790
|
+
session; `pmcp git deliver` prints the same line, with how many more delivered
|
|
791
|
+
paths matched, for each owner its commits touch. Declaring `[[owners]]` projects
|
|
792
|
+
the hook bundle. [`pmcp owners <path>`](commands.md#owners) answers for any path.
|
|
793
|
+
|
|
794
|
+
```toml
|
|
795
|
+
[[owners]]
|
|
796
|
+
paths = ["services/auth", "services/billing"]
|
|
797
|
+
owner = "hub team"
|
|
798
|
+
note = "tell them before you land a change here"
|
|
799
|
+
```
|
|
800
|
+
|
|
736
801
|
## Git workflow
|
|
737
802
|
|
|
738
803
|
Worktrees, delivery to the mainline and main checkout sync: [Git workflow](git-workflow.md).
|
|
@@ -741,9 +806,11 @@ Worktrees, delivery to the mainline and main checkout sync: [Git workflow](git-w
|
|
|
741
806
|
|
|
742
807
|
`[budget]` sets limits on what every agent session loads and on paths the
|
|
743
808
|
project keeps out of its tree. `pmcp project --check` exits 4 when one is
|
|
744
|
-
exceeded, naming each, and `pmcp status`
|
|
745
|
-
limits (its JSON gains `budget: {rows, problems}
|
|
746
|
-
|
|
809
|
+
exceeded, naming each, and `pmcp status` reports the measurements beside the
|
|
810
|
+
limits (its JSON gains `budget: {rows, problems}`) without judging them: an
|
|
811
|
+
exceeded limit is not drift and leaves its exit code alone, so `project --check`
|
|
812
|
+
stays the one judge. Every key is optional; nothing is checked without the
|
|
813
|
+
table.
|
|
747
814
|
|
|
748
815
|
| Key | Type | Meaning |
|
|
749
816
|
| --------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
@@ -762,6 +829,27 @@ skills_max = 40
|
|
|
762
829
|
forbid_paths = [".spec/**", "docs/adr"]
|
|
763
830
|
```
|
|
764
831
|
|
|
832
|
+
A project whose document limits another checker judges leaves those keys out of
|
|
833
|
+
`[budget]` and keeps the numbers in `[budgets]` instead.
|
|
834
|
+
|
|
835
|
+
## Budgets
|
|
836
|
+
|
|
837
|
+
`[budgets]` holds byte and line limits per path glob, so the numbers live in one
|
|
838
|
+
place while another tool judges them. Each key is a project-relative glob, as in
|
|
839
|
+
`forbid_paths`, and each value an inline table with `bytes`, `lines` or both
|
|
840
|
+
(whole numbers from 1); any other key, or an entry with neither, is a
|
|
841
|
+
configuration error. pmcp validates the table and judges none of it: neither
|
|
842
|
+
`project --check` nor `status` measures it. A checker reads it from `pmcp.toml`
|
|
843
|
+
at the TOML path `budgets` (how overlapping globs combine is the checker's), and
|
|
844
|
+
an [external guard](hooks.md#hooksguardsexternal) can run that checker on every
|
|
845
|
+
edit of a matching file.
|
|
846
|
+
|
|
847
|
+
```toml
|
|
848
|
+
[budgets]
|
|
849
|
+
"**/AGENTS.md" = { bytes = 4096 }
|
|
850
|
+
"AGENTS.md" = { bytes = 12288, lines = 200 }
|
|
851
|
+
```
|
|
852
|
+
|
|
765
853
|
## Logging
|
|
766
854
|
|
|
767
855
|
| `[logging]` key | Type | Default | Allowed |
|
|
@@ -839,6 +927,9 @@ publish = ["deploy", "secret put", "secret delete"]
|
|
|
839
927
|
[hooks.guards.shell.runaway_regex]
|
|
840
928
|
threshold = 255
|
|
841
929
|
|
|
930
|
+
[hooks.guards.shell.self_matching_wait]
|
|
931
|
+
mode = "deny"
|
|
932
|
+
|
|
842
933
|
[hooks.guards.git.push_without_verify]
|
|
843
934
|
|
|
844
935
|
[hooks.guards.git.forced_branch_move]
|
|
@@ -860,6 +951,11 @@ command = ["node", "{validator}"]
|
|
|
860
951
|
|
|
861
952
|
[hooks.checks.on_stop]
|
|
862
953
|
|
|
954
|
+
[[owners]]
|
|
955
|
+
paths = ["services/auth"]
|
|
956
|
+
owner = "hub team"
|
|
957
|
+
note = "tell them before you land a change here"
|
|
958
|
+
|
|
863
959
|
[sessions]
|
|
864
960
|
state_dir = ".pmcp-state"
|
|
865
961
|
|
package/docs/sessions.md
CHANGED
|
@@ -33,8 +33,15 @@ pmcp sessions sweep # drop records whose process is gone
|
|
|
33
33
|
|
|
34
34
|
While paused, every other session's edits and mutating commands are refused; reading and
|
|
35
35
|
planning continue. A broadcast reaches each running session once, as context. `--by <name>`
|
|
36
|
-
names who pauses or broadcasts; that session is exempt
|
|
37
|
-
`operator
|
|
36
|
+
names who pauses or broadcasts; that session is exempt. Without it a broadcast is signed by
|
|
37
|
+
the agent session it runs in, or by `operator` from your own terminal.
|
|
38
|
+
|
|
39
|
+
Pause and resume are [operator verbs](project-configuration.md#the-operator): pmcp runs them
|
|
40
|
+
only from your terminal (or with your operator token), refuses them inside an agent session
|
|
41
|
+
with a line telling the agent to ask you, and the `pmcp.operator_verbs` guard refuses them in
|
|
42
|
+
the agent's runtime before they start. The same holds for `pmcp heavy --now`,
|
|
43
|
+
`pmcp heavy promote --now`, `pmcp heavy cancel --force` on another session's job and
|
|
44
|
+
`pmcp git deliver --during-pause`.
|
|
38
45
|
|
|
39
46
|
## Send a message to one session
|
|
40
47
|
|
package/docs/upgrading.md
CHANGED
|
@@ -5,6 +5,77 @@
|
|
|
5
5
|
What to do when a release changes something you rely on. Each release's notes on GitHub
|
|
6
6
|
Releases list its breaking changes and link here.
|
|
7
7
|
|
|
8
|
+
## From 0.25 to 0.26
|
|
9
|
+
|
|
10
|
+
**`pmcp status` no longer judges `[budget]`.** It still shows each limit beside what it
|
|
11
|
+
measured and how many are over, in the summary and in `data.budget`, but an exceeded limit
|
|
12
|
+
no longer sets `drift` or exit 4; only projection drift does. `pmcp project --check` still
|
|
13
|
+
exits 4 over a limit. A script that relied on `pmcp status` failing over a budget runs
|
|
14
|
+
`pmcp project --check`, or reads `data.budget.problems` from `pmcp status --json`.
|
|
15
|
+
|
|
16
|
+
**A blocking `pmcp heavy` run keeps its command's output.** The command's stdout and
|
|
17
|
+
stderr now pass through pmcp, which copies them into the run's ticket, so the command sees
|
|
18
|
+
pipes rather than a terminal (no colours or progress bars from tools that check). Set
|
|
19
|
+
`[host.lease] job_log_bytes = 0` to keep the terminal and keep no copy.
|
|
20
|
+
|
|
21
|
+
## From 0.24 to 0.25
|
|
22
|
+
|
|
23
|
+
**`pmcp status` exits 4 only for projection drift or a budget overrun.** A linked worktree
|
|
24
|
+
ahead of or behind the mainline no longer sets `drift` or the exit code; it is counted in
|
|
25
|
+
the summary line and in the new `data.lagging` field. A script that relied on exit 4 to
|
|
26
|
+
notice worktree lag reads `lagging` from `pmcp status --json` instead.
|
|
27
|
+
|
|
28
|
+
**Operator verbs run only as the operator.** `pmcp sessions pause` and `resume`,
|
|
29
|
+
`pmcp heavy --now` (and `PMCP_HEAVY_NOW`), `pmcp heavy promote --now`,
|
|
30
|
+
`pmcp heavy cancel --force` on another session's job and `pmcp git deliver --during-pause`
|
|
31
|
+
now exit 1 inside an agent session, with a line telling the agent to ask you. From your own
|
|
32
|
+
terminal nothing changes. A script or cron job that runs one of them has no terminal: give
|
|
33
|
+
it an operator token,
|
|
34
|
+
|
|
35
|
+
```toml
|
|
36
|
+
[sessions.operator]
|
|
37
|
+
via = "token"
|
|
38
|
+
token_file = "~/.config/pmcp/operator-token" # outside the project, chmod 600
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
and run it with `PMCP_OPERATOR_TOKEN` set to the file's contents. A gate or hook that ran
|
|
42
|
+
`pmcp heavy --now` for its own stages should use the `gate` or `hook` profile, or a reason
|
|
43
|
+
in `[host.lease] skip_always`, instead.
|
|
44
|
+
|
|
45
|
+
**`--by` no longer defaults to `operator`.** `pmcp sessions broadcast`, `send` and `reply`
|
|
46
|
+
sign with the agent session they run in, or with `operator` only from the operator's
|
|
47
|
+
terminal; `--by operator` anywhere else exits 2. A command run inside a runtime whose
|
|
48
|
+
session pmcp cannot find (Gemini CLI, OpenCode) now exits 2 asking for `--session <id>` or
|
|
49
|
+
`--by <name>` instead of acting as the operator.
|
|
50
|
+
|
|
51
|
+
**The `pmcp.operator_verbs` guard is on with any session feature.** A project that declares
|
|
52
|
+
`[sessions.registry]`, `[sessions.pause]` or another session table gets it in deny mode;
|
|
53
|
+
run `pmcp project` once so the hook policy carries it (`pmcp project --check` reports the
|
|
54
|
+
drift until then). Turn it off with
|
|
55
|
+
`[hooks.guards.pmcp.operator_verbs]` `mode = "off"`.
|
|
56
|
+
|
|
57
|
+
**Lease skip reasons are a closed set.** `PMCP_HEAVY_DISABLE=<reason>` (and the
|
|
58
|
+
`legacy_skip_env` variable) is honoured only for `nested` (set by pmcp inside a leased job,
|
|
59
|
+
and honoured only there), `operator` (only for the operator) and the names you list:
|
|
60
|
+
|
|
61
|
+
```toml
|
|
62
|
+
[host.lease]
|
|
63
|
+
skip_reasons = ["ci", "subagent-no-lease"] # ordinary commands
|
|
64
|
+
skip_always = ["git-hook", "gate-light"] # also bulk jobs; allowed as reasons too
|
|
65
|
+
```
|
|
66
|
+
|
|
67
|
+
Any other reason runs nothing and `pmcp heavy` exits 2 with the allowed list. A wrapper
|
|
68
|
+
that read the old nested value `inside pmcp heavy <pid>` now sees `nested`; the old
|
|
69
|
+
value is still read as `nested` until 0.26. Reasons are lower-case words, so a
|
|
70
|
+
`skip_always` entry with spaces or capitals is now a configuration error.
|
|
71
|
+
|
|
72
|
+
**A declared `[host.lease]` turns the `host.lease` guard on in observe.** Without a
|
|
73
|
+
`heavy` list, the table now gets pmcp's `"default"` preset (install, test, build and
|
|
74
|
+
typecheck for npm, pnpm, yarn, bun and cargo), so the guard logs what it would refuse.
|
|
75
|
+
Run `pmcp project` to project it; set `heavy = []` to keep the guard off. A finding an
|
|
76
|
+
`observe` or `warn` guard let through is now logged at info: after a week,
|
|
77
|
+
`pmcp hooks report --switch-check host.lease` shows what `guard = "deny"` would refuse.
|
|
78
|
+
|
|
8
79
|
## From 0.23 to 0.24
|
|
9
80
|
|
|
10
81
|
**A lease skip no longer covers a bulk job.** `PMCP_HEAVY_DISABLE=<reason>` (or the
|
package/gemini-extension.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pmcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.26.0",
|
|
4
4
|
"mcpServers": {
|
|
5
5
|
"pmcp": {
|
|
6
6
|
"type": "stdio",
|
|
7
7
|
"command": "npx",
|
|
8
|
-
"args": ["-y", "@modootoday/pmcp@0.
|
|
8
|
+
"args": ["-y", "@modootoday/pmcp@0.26.0", "serve"]
|
|
9
9
|
}
|
|
10
10
|
}
|
|
11
11
|
}
|
package/mcp.json
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@modootoday/pmcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.26.0",
|
|
4
4
|
"license": "Elastic-2.0",
|
|
5
5
|
"author": "modootoday",
|
|
6
6
|
"description": "Use the skills your packages already ship, and keep your AI tools' project configuration in one place.",
|
|
@@ -136,9 +136,9 @@
|
|
|
136
136
|
"bun": ">=1.3.0"
|
|
137
137
|
},
|
|
138
138
|
"optionalDependencies": {
|
|
139
|
-
"@modootoday/pmcp-linux-x64": "0.
|
|
140
|
-
"@modootoday/pmcp-linux-arm64": "0.
|
|
141
|
-
"@modootoday/pmcp-darwin-x64": "0.
|
|
142
|
-
"@modootoday/pmcp-darwin-arm64": "0.
|
|
139
|
+
"@modootoday/pmcp-linux-x64": "0.26.0",
|
|
140
|
+
"@modootoday/pmcp-linux-arm64": "0.26.0",
|
|
141
|
+
"@modootoday/pmcp-darwin-x64": "0.26.0",
|
|
142
|
+
"@modootoday/pmcp-darwin-arm64": "0.26.0"
|
|
143
143
|
}
|
|
144
144
|
}
|
package/plugin.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
|
3
3
|
"name": "pmcp",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.26.0",
|
|
5
5
|
"description": "Find package skills and use native runtime project configuration.",
|
|
6
6
|
"author": { "name": "modootoday" },
|
|
7
7
|
"license": "Elastic-2.0",
|
package/plugins/pmcp/.mcp.json
CHANGED
|
@@ -1,11 +1,11 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "pmcp",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.26.0",
|
|
4
4
|
"mcpServers": {
|
|
5
5
|
"pmcp": {
|
|
6
6
|
"type": "stdio",
|
|
7
7
|
"command": "npx",
|
|
8
|
-
"args": ["-y", "@modootoday/pmcp@0.
|
|
8
|
+
"args": ["-y", "@modootoday/pmcp@0.26.0", "serve"]
|
|
9
9
|
}
|
|
10
10
|
}
|
|
11
11
|
}
|
package/plugins/pmcp/mcp.json
CHANGED
package/plugins/pmcp/plugin.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
|
|
3
3
|
"name": "pmcp",
|
|
4
|
-
"version": "0.
|
|
4
|
+
"version": "0.26.0",
|
|
5
5
|
"description": "Find package skills and use native runtime project configuration.",
|
|
6
6
|
"author": { "name": "modootoday" },
|
|
7
7
|
"license": "Elastic-2.0",
|
package/dist/chunk-65H4PN33.js
DELETED
package/dist/chunk-7TD53M7L.js
DELETED
|
@@ -1,13 +0,0 @@
|
|
|
1
|
-
// src/hooks/inspection/source.ts
|
|
2
|
-
function sourceFor(id) {
|
|
3
|
-
if (id.startsWith("custom.")) return "hooks.guards.custom";
|
|
4
|
-
if (id.startsWith("checks.")) return "hooks." + id;
|
|
5
|
-
if (id.startsWith("sessions.") || id.startsWith("git.worktrees") || id === "git.shared_checkout" || id === "git.mainline.deliver")
|
|
6
|
-
return id;
|
|
7
|
-
return "hooks.guards." + id;
|
|
8
|
-
}
|
|
9
|
-
|
|
10
|
-
export {
|
|
11
|
-
sourceFor
|
|
12
|
-
};
|
|
13
|
-
//# sourceMappingURL=chunk-7TD53M7L.js.map
|
package/dist/chunk-FQLCD4HU.js
DELETED
|
@@ -1,24 +0,0 @@
|
|
|
1
|
-
import {
|
|
2
|
-
expandPath
|
|
3
|
-
} from "./chunk-GUHOEIHP.js";
|
|
4
|
-
import {
|
|
5
|
-
gitCommonDir
|
|
6
|
-
} from "./chunk-IJBSOWHK.js";
|
|
7
|
-
|
|
8
|
-
// src/sessions/state-dir.ts
|
|
9
|
-
import { createHash } from "crypto";
|
|
10
|
-
import { realpathSync } from "fs";
|
|
11
|
-
import { homedir } from "os";
|
|
12
|
-
import { join } from "path";
|
|
13
|
-
function projectStateDir(root, override, env = process.env) {
|
|
14
|
-
if (override) return expandPath(root, override);
|
|
15
|
-
const anchor = gitCommonDir(root) ?? realpathSync(root);
|
|
16
|
-
const id = createHash("sha256").update(anchor).digest("hex").slice(0, 16);
|
|
17
|
-
const base = env["XDG_STATE_HOME"] || join(homedir(), ".local", "state");
|
|
18
|
-
return join(base, "pmcp", "projects", id);
|
|
19
|
-
}
|
|
20
|
-
|
|
21
|
-
export {
|
|
22
|
-
projectStateDir
|
|
23
|
-
};
|
|
24
|
-
//# sourceMappingURL=chunk-FQLCD4HU.js.map
|