@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
|
@@ -0,0 +1,73 @@
|
|
|
1
|
+
// Keep enforcement in hooks so the mod only presents state and relays operator choices.
|
|
2
|
+
import { atom, read, type On } from "claude-code";
|
|
3
|
+
import { runCommand } from "./commands";
|
|
4
|
+
import { drawBand, drawPane } from "./draw";
|
|
5
|
+
import { holdForeignEdit } from "./guard";
|
|
6
|
+
import { findSettings, resolveStateDir } from "./host";
|
|
7
|
+
import { refresh } from "./snapshot";
|
|
8
|
+
import { EDITS, PANE_ID, POLL_MS, state, type Kept } from "./state";
|
|
9
|
+
|
|
10
|
+
// The same host-kept value snapshot.ts updates; declared here so the host scan can follow it.
|
|
11
|
+
const kept = atom(
|
|
12
|
+
{ plugin: "pmcp", key: "kept" } as const,
|
|
13
|
+
null as Kept | null,
|
|
14
|
+
);
|
|
15
|
+
|
|
16
|
+
async function start($: any, e: any): Promise<void> {
|
|
17
|
+
state.self = await $.session.id();
|
|
18
|
+
const cwd = String(e?.cwd ?? (await $.env.get("PWD")) ?? "");
|
|
19
|
+
const found = await findSettings($, cwd);
|
|
20
|
+
if (!found) return;
|
|
21
|
+
const stateDir = await resolveStateDir($, found.root, found.settings);
|
|
22
|
+
if (!stateDir) return;
|
|
23
|
+
state.root = found.root;
|
|
24
|
+
state.settings = found.settings;
|
|
25
|
+
state.stateDir = stateDir;
|
|
26
|
+
const saved = await read($, kept);
|
|
27
|
+
if (saved) {
|
|
28
|
+
state.snapshot = saved.snapshot;
|
|
29
|
+
state.isOpen = saved.isOpen;
|
|
30
|
+
state.now = saved.now;
|
|
31
|
+
}
|
|
32
|
+
if (found.settings.commands) {
|
|
33
|
+
await $.command
|
|
34
|
+
.register({
|
|
35
|
+
name: "pmcp",
|
|
36
|
+
description:
|
|
37
|
+
"Sessions pane; /pmcp pause <reason> stops every other session, /pmcp resume lifts it, /pmcp broadcast <text> tells every session",
|
|
38
|
+
argumentHint:
|
|
39
|
+
"[pause <reason> | resume | broadcast <text> | unbroadcast]",
|
|
40
|
+
})
|
|
41
|
+
.catch(() => undefined);
|
|
42
|
+
}
|
|
43
|
+
$.clock.every(POLL_MS, () => {
|
|
44
|
+
void refresh($).catch(() => undefined);
|
|
45
|
+
});
|
|
46
|
+
await refresh($).catch(() => undefined);
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
export function register(on: On): void {
|
|
50
|
+
on("session.start", async ($: any, e: any, next: any) => {
|
|
51
|
+
await start($, e).catch(() => undefined);
|
|
52
|
+
return next(e);
|
|
53
|
+
});
|
|
54
|
+
on("command.run", { command: "pmcp" }, async ($: any, e: any, next: any) =>
|
|
55
|
+
state.settings?.commands ? runCommand($, String(e.args ?? "")) : next(e),
|
|
56
|
+
);
|
|
57
|
+
on("ui.render", { component: "Pane" }, async ($: any, e: any, next: any) =>
|
|
58
|
+
e.requestId === PANE_ID && state.settings?.sessionsPane
|
|
59
|
+
? drawPane($, e)
|
|
60
|
+
: next(e),
|
|
61
|
+
);
|
|
62
|
+
on(
|
|
63
|
+
"ui.render",
|
|
64
|
+
{ component: "AbovePrompt" },
|
|
65
|
+
async ($: any, e: any, next: any) =>
|
|
66
|
+
state.settings?.statusBand ? drawBand($, e, next) : next(e),
|
|
67
|
+
);
|
|
68
|
+
on("tool.call", { tool: EDITS }, async ($: any, e: any, next: any) =>
|
|
69
|
+
state.settings?.holdForeignEdits
|
|
70
|
+
? holdForeignEdit($, e, next).catch(() => next(e))
|
|
71
|
+
: next(e),
|
|
72
|
+
);
|
|
73
|
+
}
|
|
@@ -0,0 +1,91 @@
|
|
|
1
|
+
// Keep format definitions dependency-free so the mod can ship the same store contract.
|
|
2
|
+
|
|
3
|
+
import type { Broadcast, Lease, Pause, SessionRecord } from "./types";
|
|
4
|
+
|
|
5
|
+
export const STATE_FILES = {
|
|
6
|
+
records: "fleet",
|
|
7
|
+
pause: "pause.json",
|
|
8
|
+
broadcast: "broadcast.json",
|
|
9
|
+
history: "broadcast-history.jsonl",
|
|
10
|
+
} as const;
|
|
11
|
+
|
|
12
|
+
export const STALE_MS = 30 * 60 * 1000;
|
|
13
|
+
|
|
14
|
+
const LEASE_NAME = /^[a-z0-9][a-z0-9_-]*$/u;
|
|
15
|
+
|
|
16
|
+
// Preserve the existing lockfile lease filename so delivery and hook readers remain compatible.
|
|
17
|
+
export function leaseFile(name: string): string {
|
|
18
|
+
if (!LEASE_NAME.test(name)) throw new Error(`invalid lease name ${name}`);
|
|
19
|
+
return `${name}-lease.json`;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
type Fields = Record<string, unknown>;
|
|
23
|
+
|
|
24
|
+
const text = (value: unknown): value is string => typeof value === "string";
|
|
25
|
+
|
|
26
|
+
export function fieldsOf(value: unknown): Fields | null {
|
|
27
|
+
if (value === null || typeof value !== "object" || Array.isArray(value))
|
|
28
|
+
return null;
|
|
29
|
+
return value as Fields;
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
export function asPause(value: unknown): Pause | null {
|
|
33
|
+
const fields = fieldsOf(value);
|
|
34
|
+
if (
|
|
35
|
+
!fields ||
|
|
36
|
+
!text(fields["by"]) ||
|
|
37
|
+
!text(fields["reason"]) ||
|
|
38
|
+
!text(fields["since"])
|
|
39
|
+
)
|
|
40
|
+
return null;
|
|
41
|
+
return { by: fields["by"], reason: fields["reason"], since: fields["since"] };
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export function asLease(value: unknown): Lease | null {
|
|
45
|
+
const fields = fieldsOf(value);
|
|
46
|
+
if (!fields || typeof fields["pid"] !== "number" || !text(fields["subject"]))
|
|
47
|
+
return null;
|
|
48
|
+
const cwd = text(fields["cwd"]) ? { cwd: fields["cwd"] } : {};
|
|
49
|
+
return {
|
|
50
|
+
pid: fields["pid"],
|
|
51
|
+
subject: fields["subject"],
|
|
52
|
+
since: text(fields["since"]) ? fields["since"] : "",
|
|
53
|
+
...cwd,
|
|
54
|
+
};
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
export function asBroadcast(value: unknown): Broadcast | null {
|
|
58
|
+
const fields = fieldsOf(value);
|
|
59
|
+
if (
|
|
60
|
+
!fields ||
|
|
61
|
+
!text(fields["id"]) ||
|
|
62
|
+
!text(fields["by"]) ||
|
|
63
|
+
!text(fields["text"]) ||
|
|
64
|
+
!text(fields["since"])
|
|
65
|
+
) {
|
|
66
|
+
return null;
|
|
67
|
+
}
|
|
68
|
+
return {
|
|
69
|
+
id: fields["id"],
|
|
70
|
+
by: fields["by"],
|
|
71
|
+
text: fields["text"],
|
|
72
|
+
since: fields["since"],
|
|
73
|
+
};
|
|
74
|
+
}
|
|
75
|
+
|
|
76
|
+
export function asRecord(value: unknown): SessionRecord | null {
|
|
77
|
+
const fields = fieldsOf(value);
|
|
78
|
+
if (!fields || !text(fields["session"])) return null;
|
|
79
|
+
return fields as SessionRecord;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
export function recordLive(
|
|
83
|
+
record: SessionRecord,
|
|
84
|
+
now: number,
|
|
85
|
+
pidAlive: boolean,
|
|
86
|
+
staleMs = STALE_MS,
|
|
87
|
+
): boolean {
|
|
88
|
+
if (record.pid !== undefined) return pidAlive;
|
|
89
|
+
const beat = Date.parse(record.updatedAt ?? "");
|
|
90
|
+
return Number.isFinite(beat) && now - beat < staleMs;
|
|
91
|
+
}
|
|
@@ -0,0 +1,162 @@
|
|
|
1
|
+
// Preserve state field names so existing coordination readers remain compatible.
|
|
2
|
+
|
|
3
|
+
export interface TouchedPath {
|
|
4
|
+
readonly path: string;
|
|
5
|
+
readonly at: string;
|
|
6
|
+
}
|
|
7
|
+
|
|
8
|
+
export interface SessionRecord {
|
|
9
|
+
readonly session: string;
|
|
10
|
+
readonly startedAt?: string;
|
|
11
|
+
|
|
12
|
+
readonly updatedAt?: string;
|
|
13
|
+
readonly pid?: number;
|
|
14
|
+
readonly runtime?: string;
|
|
15
|
+
readonly alias?: string;
|
|
16
|
+
readonly cwd?: string;
|
|
17
|
+
readonly worktree?: string;
|
|
18
|
+
readonly branch?: string;
|
|
19
|
+
readonly status?: "idle" | "working" | "waiting";
|
|
20
|
+
readonly waiting?: string;
|
|
21
|
+
readonly source?: string;
|
|
22
|
+
readonly lastAction?: string;
|
|
23
|
+
readonly lastMessage?: string;
|
|
24
|
+
readonly seenBroadcast?: string;
|
|
25
|
+
readonly stopNoticeTurn?: string;
|
|
26
|
+
readonly sharedRoot?: string;
|
|
27
|
+
readonly sharedTouched?: readonly TouchedPath[];
|
|
28
|
+
readonly sharedEditNoticed?: boolean;
|
|
29
|
+
readonly sharedNoticed?: string;
|
|
30
|
+
readonly sharedWarned?: boolean;
|
|
31
|
+
readonly [key: string]: unknown;
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
export interface LiveRecord extends SessionRecord {
|
|
35
|
+
readonly live: boolean;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
export interface Pause {
|
|
39
|
+
readonly by: string;
|
|
40
|
+
readonly reason: string;
|
|
41
|
+
readonly since: string;
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
export interface Lease {
|
|
45
|
+
readonly pid: number;
|
|
46
|
+
readonly subject: string;
|
|
47
|
+
readonly cwd?: string;
|
|
48
|
+
readonly since: string;
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
export interface Broadcast {
|
|
52
|
+
readonly id: string;
|
|
53
|
+
readonly by: string;
|
|
54
|
+
readonly text: string;
|
|
55
|
+
readonly since: string;
|
|
56
|
+
}
|
|
57
|
+
|
|
58
|
+
export interface SessionStore {
|
|
59
|
+
readonly dir: string;
|
|
60
|
+
readonly registry: {
|
|
61
|
+
get(session: string): SessionRecord | null;
|
|
62
|
+
|
|
63
|
+
upsert(
|
|
64
|
+
session: string,
|
|
65
|
+
fields: Partial<SessionRecord>,
|
|
66
|
+
): SessionRecord | null;
|
|
67
|
+
list(now?: number): LiveRecord[];
|
|
68
|
+
remove(session: string): void;
|
|
69
|
+
|
|
70
|
+
sweep(now?: number): number;
|
|
71
|
+
};
|
|
72
|
+
readonly pause: {
|
|
73
|
+
read(): Pause | null;
|
|
74
|
+
write(pause: { by: string; reason: string } | null): void;
|
|
75
|
+
};
|
|
76
|
+
readonly leases: {
|
|
77
|
+
read(name: string): Lease | null;
|
|
78
|
+
take(
|
|
79
|
+
name: string,
|
|
80
|
+
lease: { subject: string; cwd?: string; pid?: number },
|
|
81
|
+
): boolean;
|
|
82
|
+
release(name: string, pid?: number): void;
|
|
83
|
+
};
|
|
84
|
+
readonly broadcast: {
|
|
85
|
+
list(): Broadcast[];
|
|
86
|
+
|
|
87
|
+
unseen(session: string): Broadcast[];
|
|
88
|
+
post(broadcast: { by: string; text: string }): Broadcast;
|
|
89
|
+
clear(): void;
|
|
90
|
+
};
|
|
91
|
+
readonly mailbox: Mailbox;
|
|
92
|
+
}
|
|
93
|
+
|
|
94
|
+
export interface MessageFrom {
|
|
95
|
+
readonly session?: string;
|
|
96
|
+
readonly alias?: string;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
// One file per message, never rewritten; acks and deliveries are separate markers.
|
|
100
|
+
export interface Message {
|
|
101
|
+
readonly id: string;
|
|
102
|
+
readonly from: MessageFrom;
|
|
103
|
+
// Selectors: all, session:<id>, alias:<name>, role:<name>, worktree:<path> (alias desk:<path>).
|
|
104
|
+
readonly to: readonly string[];
|
|
105
|
+
readonly subject?: string;
|
|
106
|
+
readonly body: string;
|
|
107
|
+
readonly createdAt: string;
|
|
108
|
+
readonly expiresAt: string;
|
|
109
|
+
readonly replyTo?: string;
|
|
110
|
+
readonly once: boolean;
|
|
111
|
+
// Set when the message carries a broadcast, so broadcast.json readers stay in step.
|
|
112
|
+
readonly broadcastId?: string;
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
export interface Recipient {
|
|
116
|
+
// The inbox key: a session id, or @<alias> for someone outside a session.
|
|
117
|
+
readonly key: string;
|
|
118
|
+
readonly session?: string;
|
|
119
|
+
readonly alias?: string;
|
|
120
|
+
readonly roles?: readonly string[];
|
|
121
|
+
readonly desk?: string;
|
|
122
|
+
// When the session started: a broadcast to all sent before then is not for it.
|
|
123
|
+
readonly since?: string;
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
export interface MailboxSettings {
|
|
127
|
+
readonly enabled: boolean;
|
|
128
|
+
readonly ttlMinutes: number;
|
|
129
|
+
readonly maxDelivered: number;
|
|
130
|
+
readonly audit: boolean;
|
|
131
|
+
// Wake idle recipients on send where their runtime allows it (Claude inbox, opencode server).
|
|
132
|
+
readonly wake?: boolean;
|
|
133
|
+
}
|
|
134
|
+
|
|
135
|
+
export interface SendInput {
|
|
136
|
+
readonly from: MessageFrom;
|
|
137
|
+
readonly to: readonly string[];
|
|
138
|
+
readonly body: string;
|
|
139
|
+
readonly subject?: string;
|
|
140
|
+
readonly ttlMinutes?: number;
|
|
141
|
+
readonly replyTo?: string;
|
|
142
|
+
readonly once?: boolean;
|
|
143
|
+
readonly broadcastId?: string;
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
export interface Mailbox {
|
|
147
|
+
readonly settings: MailboxSettings;
|
|
148
|
+
send(input: SendInput): Message;
|
|
149
|
+
get(id: string): Message | null;
|
|
150
|
+
// Unexpired messages, oldest first.
|
|
151
|
+
list(now?: number): Message[];
|
|
152
|
+
// Unexpired, unacked messages addressed to the recipient and not sent by it.
|
|
153
|
+
inbox(recipient: Recipient, now?: number): Message[];
|
|
154
|
+
delivered(key: string, id: string): boolean;
|
|
155
|
+
markDelivered(key: string, ids: readonly string[]): void;
|
|
156
|
+
acked(key: string, id: string): boolean;
|
|
157
|
+
ack(key: string, ids: readonly string[]): string[];
|
|
158
|
+
withdraw(match: (message: Message) => boolean): number;
|
|
159
|
+
sweep(now?: number): number;
|
|
160
|
+
// Appends an audit line for something done outside the store, such as a wake.
|
|
161
|
+
record(event: string, fields: Readonly<Record<string, unknown>>): void;
|
|
162
|
+
}
|
|
@@ -0,0 +1,75 @@
|
|
|
1
|
+
import { atom, update } from "claude-code";
|
|
2
|
+
import { hostFiles } from "./host";
|
|
3
|
+
import { blocking, byKind, nameOf, stuck, summaryOf, waitingOf } from "./model";
|
|
4
|
+
import { readSessionState, type SessionSnapshot } from "./reader/index";
|
|
5
|
+
import { state, type Kept } from "./state";
|
|
6
|
+
|
|
7
|
+
// Retain state through the host because module variables reset when the mod reloads.
|
|
8
|
+
const kept = atom(
|
|
9
|
+
{ plugin: "pmcp", key: "kept" } as const,
|
|
10
|
+
null as Kept | null,
|
|
11
|
+
);
|
|
12
|
+
|
|
13
|
+
function announce(
|
|
14
|
+
$: any,
|
|
15
|
+
before: SessionSnapshot,
|
|
16
|
+
after: SessionSnapshot,
|
|
17
|
+
): void {
|
|
18
|
+
if (!before.pause && after.pause)
|
|
19
|
+
$.ui.toast(`Sessions paused: ${after.pause.reason}`);
|
|
20
|
+
const heard = after.broadcast;
|
|
21
|
+
if (heard && heard.by !== state.self && heard.id !== before.broadcast?.id) {
|
|
22
|
+
$.ui.toast(`Broadcast: ${heard.text}`, { timeoutMs: 10000 });
|
|
23
|
+
}
|
|
24
|
+
if (before.pause && !after.pause) $.ui.toast("Sessions resumed");
|
|
25
|
+
const wasStuck = before.lease ? stuck(before.lease) : false;
|
|
26
|
+
if (after.lease && stuck(after.lease) && !wasStuck)
|
|
27
|
+
$.ui.toast(`A lease has been held for 10 min: ${after.lease.subject}`);
|
|
28
|
+
const waitingBefore = new Set(blocking(before.records).map((r) => r.session));
|
|
29
|
+
for (const record of blocking(after.records)) {
|
|
30
|
+
if (waitingBefore.has(record.session)) continue;
|
|
31
|
+
$.ui.toast(`${nameOf(record)} is asking (${waitingOf(record)})`, {
|
|
32
|
+
timeoutMs: 8000,
|
|
33
|
+
});
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
|
|
37
|
+
// Redraw only visible changes so peer activity does not disrupt scrolled views.
|
|
38
|
+
function drawnSignature(snapshot: SessionSnapshot): string {
|
|
39
|
+
const band = {
|
|
40
|
+
pause: snapshot.pause,
|
|
41
|
+
lease:
|
|
42
|
+
snapshot.lease && stuck(snapshot.lease) ? snapshot.lease.subject : null,
|
|
43
|
+
broadcast: snapshot.broadcast?.id ?? null,
|
|
44
|
+
asking: blocking(snapshot.records).map((r) => r.session),
|
|
45
|
+
summary: summaryOf(snapshot),
|
|
46
|
+
};
|
|
47
|
+
if (!state.isOpen) return JSON.stringify(band);
|
|
48
|
+
return JSON.stringify({
|
|
49
|
+
band,
|
|
50
|
+
records: snapshot.records,
|
|
51
|
+
lease: snapshot.lease?.subject ?? null,
|
|
52
|
+
tick: Math.floor(state.now / 10_000),
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
export async function refresh($: any): Promise<void> {
|
|
57
|
+
if (!state.settings) return;
|
|
58
|
+
state.now = Number(await $.clock.now());
|
|
59
|
+
const read = await readSessionState(hostFiles($), {
|
|
60
|
+
stateDir: state.stateDir,
|
|
61
|
+
now: state.now,
|
|
62
|
+
});
|
|
63
|
+
const next = { ...read, records: [...read.records].sort(byKind) };
|
|
64
|
+
announce($, state.snapshot, next);
|
|
65
|
+
state.snapshot = next;
|
|
66
|
+
const signature = drawnSignature(next);
|
|
67
|
+
if (signature === state.signature) return;
|
|
68
|
+
state.signature = signature;
|
|
69
|
+
await update($, kept, () => ({
|
|
70
|
+
snapshot: next,
|
|
71
|
+
isOpen: state.isOpen,
|
|
72
|
+
now: state.now,
|
|
73
|
+
}));
|
|
74
|
+
await $.ui.invalidate("ui.render");
|
|
75
|
+
}
|
|
@@ -0,0 +1,30 @@
|
|
|
1
|
+
/* @jsxRuntime classic */
|
|
2
|
+
/* @jsx h */
|
|
3
|
+
/* @jsxFrag Fragment */
|
|
4
|
+
// Use an independent animation clock so spinner motion does not redraw the whole sessions pane.
|
|
5
|
+
import type { ClientModule } from "claude-code";
|
|
6
|
+
|
|
7
|
+
const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
|
|
8
|
+
const FRAME_MS = 120;
|
|
9
|
+
|
|
10
|
+
type Props = { color: string; background: string };
|
|
11
|
+
type State = { frame: number };
|
|
12
|
+
|
|
13
|
+
const Spinner: ClientModule<Props, State> = (props, surface) => {
|
|
14
|
+
const { Text } = surface.elements;
|
|
15
|
+
if (surface.state === undefined) {
|
|
16
|
+
surface.every(FRAME_MS, () => {
|
|
17
|
+
const frame = ((surface.state?.frame ?? 0) + 1) % FRAMES.length;
|
|
18
|
+
surface.setState({ frame });
|
|
19
|
+
});
|
|
20
|
+
surface.setState({ frame: 0 });
|
|
21
|
+
}
|
|
22
|
+
const frame = surface.state?.frame ?? 0;
|
|
23
|
+
return (
|
|
24
|
+
<Text color={props.color} backgroundColor={props.background} bold>
|
|
25
|
+
{FRAMES[frame]}{" "}
|
|
26
|
+
</Text>
|
|
27
|
+
);
|
|
28
|
+
};
|
|
29
|
+
|
|
30
|
+
export default Spinner;
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
import type { SessionSnapshot, UiSettings } from "./reader/index";
|
|
2
|
+
|
|
3
|
+
export const PANE_ID = "pmcp-sessions";
|
|
4
|
+
export const POLL_MS = 3000;
|
|
5
|
+
export const LEASE_STUCK_MS = 10 * 60 * 1000;
|
|
6
|
+
export const EDITS = ["Edit", "Write", "NotebookEdit"] as const;
|
|
7
|
+
|
|
8
|
+
// contract.d.ts declares pmcp/kept for the host; each reader declares its own atom for the scan.
|
|
9
|
+
export type Kept = { snapshot: SessionSnapshot; isOpen: boolean; now: number };
|
|
10
|
+
|
|
11
|
+
const EMPTY: SessionSnapshot = {
|
|
12
|
+
records: [],
|
|
13
|
+
pause: null,
|
|
14
|
+
lease: null,
|
|
15
|
+
broadcast: null,
|
|
16
|
+
};
|
|
17
|
+
|
|
18
|
+
export const state = {
|
|
19
|
+
self: "",
|
|
20
|
+
root: "",
|
|
21
|
+
|
|
22
|
+
stateDir: "",
|
|
23
|
+
settings: null as UiSettings | null,
|
|
24
|
+
isOpen: false,
|
|
25
|
+
signature: "",
|
|
26
|
+
now: 0,
|
|
27
|
+
snapshot: EMPTY,
|
|
28
|
+
};
|
package/plugins/pmcp/plugin.json
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
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.18.2",
|
|
5
5
|
"description": "Find package skills and use native runtime project configuration.",
|
|
6
6
|
"author": { "name": "modootoday" },
|
|
7
7
|
"license": "Elastic-2.0",
|
|
8
8
|
"repository": "https://github.com/modootoday/pmcp",
|
|
9
|
-
"homepage": "https://pmcp.build/
|
|
9
|
+
"homepage": "https://pmcp.build/"
|
|
10
10
|
}
|
|
@@ -0,0 +1,96 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: agent-assets-migrate
|
|
3
|
+
description: Move a repository's scattered agent files - CLAUDE.md, .cursorrules, .windsurfrules, copilot-instructions.md, .claude/skills, .claude/agents, .claude/commands, .gemini/agents and a root .agent/ folder - into one AGENTS.md, .agents/ and pmcp.toml without losing a line, keeping historical citations as they are, and finishing with a clean pmcp project --check. Use when consolidating agent instructions from several tools into one source, when adopting pmcp in a repository that already has agent files, or when agent files have drifted apart. Not for a new empty repository or for trimming an oversized AGENTS.md.
|
|
4
|
+
metadata:
|
|
5
|
+
tier: open
|
|
6
|
+
level: L3
|
|
7
|
+
domain: agent-workflow
|
|
8
|
+
install: optional
|
|
9
|
+
keywords: "migrate agent files, AGENTS.md, .agents, pmcp, CLAUDE.md, cursorrules, consolidate rules, subagents"
|
|
10
|
+
requires-bin: "pmcp"
|
|
11
|
+
---
|
|
12
|
+
|
|
13
|
+
# Migrating agent assets into AGENTS.md, .agents/ and pmcp.toml
|
|
14
|
+
|
|
15
|
+
The risk is not the move; it is silent loss. Two files that look alike usually differ by a
|
|
16
|
+
few rules, and a field one tool needed vanishes when an agent file is copied. Inventory
|
|
17
|
+
first, move verbatim, prove nothing was dropped, then let `pmcp project` regenerate the
|
|
18
|
+
tool files.
|
|
19
|
+
|
|
20
|
+
## 1. Inventory
|
|
21
|
+
|
|
22
|
+
List every source with its bytes and line count, and note which are links:
|
|
23
|
+
|
|
24
|
+
| Found | Goes to |
|
|
25
|
+
| --- | --- |
|
|
26
|
+
| `CLAUDE.md`, `GEMINI.md`, `.cursorrules`, `.windsurfrules`, `.github/copilot-instructions.md` | merged into `AGENTS.md`; each then becomes a link to it |
|
|
27
|
+
| `.claude/skills/<n>/`, `.agent/skills/<n>/` | `.agents/skills/<n>/` (whole folder) |
|
|
28
|
+
| `.claude/commands/<n>.md`, `.agent/workflows/<n>.md` | `.agents/skills/<n>/SKILL.md` plus `[skills.<n>] invocation = "user"` |
|
|
29
|
+
| `.claude/agents/<n>.md`, `.gemini/agents/<n>.md`, `.agent/agents/<n>.md` | `.agents/agents/<n>/agent.md` |
|
|
30
|
+
| `.claude/rules/*.md` with `paths:` | `.agents/rules/<n>.md` with `trigger: glob` and `globs:` |
|
|
31
|
+
| MCP entries in `.mcp.json`, `.gemini/settings.json`, `.codex/config.toml` | `[mcp.<alias>]` in `pmcp.toml` |
|
|
32
|
+
|
|
33
|
+
pmcp has no Copilot or Cursor target. Keep those filenames as links to `AGENTS.md` so they
|
|
34
|
+
cannot drift.
|
|
35
|
+
|
|
36
|
+
## 2. Merge instruction files without loss
|
|
37
|
+
|
|
38
|
+
Diff each instruction file against the others line by line. Keep the union; where two say
|
|
39
|
+
different things, settle it from the code or ask, and record the decision. Do not summarise
|
|
40
|
+
during the move. Then replace each old file with a link (`ln -s AGENTS.md CLAUDE.md`).
|
|
41
|
+
Use file-to-file links only: a directory symlink at the repository root, such as `.agents`
|
|
42
|
+
pointing at `.agent`, is rejected by the Codex sandbox.
|
|
43
|
+
|
|
44
|
+
## 3. Split agent fields
|
|
45
|
+
|
|
46
|
+
A subagent's `agent.md` keeps only `name`, `description` and the body. Everything else is
|
|
47
|
+
tool-specific and becomes a `pmcp.toml` table:
|
|
48
|
+
|
|
49
|
+
```toml
|
|
50
|
+
[agents.reviewer.claude]
|
|
51
|
+
tools = "Read, Grep, Glob"
|
|
52
|
+
model = "sonnet"
|
|
53
|
+
effort = "high"
|
|
54
|
+
```
|
|
55
|
+
|
|
56
|
+
Why: Antigravity silently drops an agent whose `tools` field lists another tool's tool
|
|
57
|
+
names. What survives projection: Claude keeps `name`, `description`, `tools`, `model`,
|
|
58
|
+
`effort`; Gemini keeps `name` and `description`; Codex gets those two plus the body. A
|
|
59
|
+
Gemini-only field has nowhere to go; list it in the report as dropped.
|
|
60
|
+
|
|
61
|
+
## 4. Keep history as it was
|
|
62
|
+
|
|
63
|
+
Change live references to the new paths: scripts, configs, current docs, other skills.
|
|
64
|
+
Leave decision records, dated plans, changelogs and evidence notes citing the old paths
|
|
65
|
+
untouched; they record what was true then. Count both groups and report them.
|
|
66
|
+
|
|
67
|
+
## 5. Remove the old copies, then project
|
|
68
|
+
|
|
69
|
+
`pmcp project` refuses to overwrite a file it did not write (exit 1, naming the file), so
|
|
70
|
+
delete the hand-written `.claude/agents/<n>.md`, `.claude/skills/<n>` and old MCP blocks
|
|
71
|
+
after their content is in the sources. Then:
|
|
72
|
+
|
|
73
|
+
```sh
|
|
74
|
+
pmcp project
|
|
75
|
+
pmcp project --check # must exit 0
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
`--check` exits 2 and names each problem: `drift` (an output differs from its source),
|
|
79
|
+
`stale` (the lock lists an output no source produces), `undeclared` (a file left in
|
|
80
|
+
`.claude/skills`, `.claude/agents`, `.claude/commands`, `.gemini/agents`, `.codex/agents`,
|
|
81
|
+
`.grok/skills` or `.claude/rules/pmcp` that nothing generates, often a copy you forgot to
|
|
82
|
+
delete), and `dead glob` (a rule glob matching no tracked file).
|
|
83
|
+
|
|
84
|
+
Codex in `workspace-write` cannot edit `.agents/` unless it is listed in
|
|
85
|
+
`sandbox_workspace_write.writable_roots`; a patch touching it is refused whole.
|
|
86
|
+
|
|
87
|
+
## 6. Prove nothing was lost
|
|
88
|
+
|
|
89
|
+
For each old file, check that every non-blank line now exists in a source (same text, or
|
|
90
|
+
a recorded decision). Count skills, agents, commands and MCP servers before and after; the
|
|
91
|
+
counts must match, with commands now counted as user-invoked skills.
|
|
92
|
+
|
|
93
|
+
## Report
|
|
94
|
+
|
|
95
|
+
The inventory table, conflicts and how each was settled, fields dropped, live and historical
|
|
96
|
+
citation counts, the before and after asset counts, and the `pmcp project --check` output.
|
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: headless-agents-ci-scaffold
|
|
3
|
+
description: Write a CI job that runs Claude Code, Gemini CLI, Codex, Grok Build and Antigravity headless against a project MCP server, giving each the permission setting it actually honours, asserting on the tool call rather than the exit code, and gating with pmcp project --check and pmcp doctor. Use when adding agent CLIs to CI, when a headless agent run skips an MCP tool call, or when a permission flag seems to do nothing. Not for interactive sessions or for writing the MCP server itself.
|
|
4
|
+
metadata:
|
|
5
|
+
tier: open
|
|
6
|
+
level: L3
|
|
7
|
+
domain: agent-workflow
|
|
8
|
+
install: optional
|
|
9
|
+
keywords: "headless agent, CI, allowedTools, permission flags, MCP permissions, Codex sandbox, Grok, Antigravity, pmcp doctor"
|
|
10
|
+
requires-bin: "pmcp"
|
|
11
|
+
verified-runtimes: "claude-code"
|
|
12
|
+
---
|
|
13
|
+
|
|
14
|
+
# Headless agent CLIs in CI
|
|
15
|
+
|
|
16
|
+
Every agent CLI blocks an MCP tool call it was not told to allow, and each spells the
|
|
17
|
+
allowance differently. Several fail quietly: the model announces the call and the run ends
|
|
18
|
+
with exit 0. So a CI job needs the right setting per tool and an assertion that the call
|
|
19
|
+
happened.
|
|
20
|
+
|
|
21
|
+
The settings below were last measured with one headless MCP call per tool (Claude Code
|
|
22
|
+
2.1.289, Gemini CLI 0.38.2, Codex 0.131.0, Grok Build 1.0.46, Antigravity 1.2.16); OpenCode,
|
|
23
|
+
also a pmcp target, was not measured, so check its own permission settings before relying on
|
|
24
|
+
a headless run. Re-check after an upgrade; these flags move.
|
|
25
|
+
|
|
26
|
+
## Permission per tool
|
|
27
|
+
|
|
28
|
+
`<server>` is the MCP alias (the `[mcp.<alias>]` name), `<tool>` the tool name.
|
|
29
|
+
|
|
30
|
+
| Tool | Command | What lets the call through |
|
|
31
|
+
| ----------- | ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
32
|
+
| Claude Code | `claude -p "<prompt>" --permission-mode default --allowedTools mcp__<server>__<tool>` | the `--allowedTools` rule; without it the call is blocked under `default` |
|
|
33
|
+
| Gemini CLI | `gemini -p "<prompt>" --allowed-mcp-server-names <server> --allowed-tools mcp_<server>_<tool>` | one `--allowed-tools` flag per tool (a bare tool name does not match; the array form swallowed the prompt); the folder must be trusted; the flag is deprecated in favour of the Policy Engine |
|
|
34
|
+
| Codex | `codex exec "<prompt>"` | nothing; `exec` allowed the call without a flag |
|
|
35
|
+
| Grok Build | `grok -p "<prompt>" --permission-mode default --allow <server>__<tool>` | `--allow <server>__<tool>`; the Claude-style `mcp__<server>__<tool>` matches nothing |
|
|
36
|
+
| Antigravity | `agy -p "<prompt>"` | a `permissions.allow` entry `mcp(<server>/<tool>)` in `~/.gemini/antigravity-cli/settings.json`; `mcp(<server>)` alone does not match, and an unlisted tool is auto-denied |
|
|
37
|
+
|
|
38
|
+
### Grok precedence traps
|
|
39
|
+
|
|
40
|
+
- Grok reads Claude Code's `~/.claude/settings.json`. A `defaultMode: auto` there approves
|
|
41
|
+
MCP calls over Grok's own `--permission-mode default` and `--disallowed-tools`. Run Grok on
|
|
42
|
+
a runner whose home has no such setting.
|
|
43
|
+
- `--permission-mode default` on the command line beats a config `permission_mode =
|
|
44
|
+
"always-approve"`, but `--disallowed-tools` does not. Do not rely on a deny rule to keep a
|
|
45
|
+
tool from running; pin the mode by flag and allow only what the job needs.
|
|
46
|
+
- A blocked call in `-p` is silent: no error line, exit 0.
|
|
47
|
+
|
|
48
|
+
### Codex sandbox
|
|
49
|
+
|
|
50
|
+
Under `--sandbox workspace-write`, `.agents/` is protected like `.git`: a patch touching it
|
|
51
|
+
is refused whole, including its other files. If the job edits `.agents/`, list it under
|
|
52
|
+
`[sandbox_workspace_write] writable_roots` in `.codex/config.toml`, or per run:
|
|
53
|
+
|
|
54
|
+
```sh
|
|
55
|
+
codex exec -s workspace-write \
|
|
56
|
+
-c 'sandbox_workspace_write.writable_roots=["<absolute repo path>/.agents"]' "<prompt>"
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
## Trust on the runner
|
|
60
|
+
|
|
61
|
+
Codex, Gemini and Grok skip project assets (skills, MCP servers, agents) in an untrusted
|
|
62
|
+
folder, without an error. On a fresh runner, record the checkout as trusted for each tool
|
|
63
|
+
before the run (Codex: `[projects."<absolute path>"] trust_level = "trusted"` in
|
|
64
|
+
`~/.codex/config.toml`; Gemini: `~/.gemini/trustedFolders.json`; Grok:
|
|
65
|
+
`~/.grok/trusted_folders.toml`; Antigravity: `trustedWorkspaces` in its settings file).
|
|
66
|
+
|
|
67
|
+
## Assert the call, not the exit code
|
|
68
|
+
|
|
69
|
+
Exit 0 proves nothing here. Either put a logging proxy in front of the MCP server and
|
|
70
|
+
assert it logged a `tools/call` for the tool, or have the prompt return a value only the
|
|
71
|
+
tool can supply and grep for it.
|
|
72
|
+
|
|
73
|
+
## Projection gate
|
|
74
|
+
|
|
75
|
+
```sh
|
|
76
|
+
pmcp project --check # exit 2: generated files drifted, went stale or are undeclared
|
|
77
|
+
pmcp doctor # exit 1 on any failed check
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
`pmcp doctor` skips a CLI that is not installed, except the Codex trust check, which reads
|
|
81
|
+
`~/.codex/config.toml` whenever `codex` is in `[targets]`. On a runner without Codex, either
|
|
82
|
+
write the trust entry or pass `--tool` for the tools present (`pmcp doctor --tool claude
|
|
83
|
+
--tool gemini`).
|
|
84
|
+
|
|
85
|
+
## Job skeleton
|
|
86
|
+
|
|
87
|
+
```sh
|
|
88
|
+
set -eu
|
|
89
|
+
pmcp project --check
|
|
90
|
+
pmcp doctor --tool claude --tool gemini --tool grok
|
|
91
|
+
out=$(claude -p "Call <tool> on <server> and print the first result name." \
|
|
92
|
+
--permission-mode default --allowedTools mcp__<server>__<tool>)
|
|
93
|
+
printf '%s\n' "$out" | grep -q '<expected value>'
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
Repeat the last two lines per tool with its own setting from the table.
|
|
97
|
+
|
|
98
|
+
## Report
|
|
99
|
+
|
|
100
|
+
The job file, the per-tool settings used with the version each was checked on, how each run
|
|
101
|
+
asserts the call, and any tool left out and why.
|