@postman/postman-plugin 0.3.0 → 0.4.1-rc.0

package/README.md

@@ -24,12 +24,30 @@ Install Postman in every compatible coding agent detected on your machine:
 npx @postman/postman-plugin
 ```
 
-One command configures **Claude Code, Codex, Cursor, Factory Droid, Kimi Code,
-OpenCode and Pi**. Run it again to update, `status` to see what's installed,
+One command configures **Antigravity, Claude Code, Codex, GitHub Copilot CLI, Cursor,
+Factory Droid, Kimi Code, OpenCode and Pi**. Run it again to update, `status` to see what's installed,
 and `remove` to uninstall; `--agent <id>` limits any of them to one agent.
 
+For Codex, installation also approves Postman's session-start hook, which adds
+instructions for using Postman's API skills. There is no separate hook prompt
+or dump of its instructions. Already trusted hooks are left alone. If Codex's
+hook API is unavailable, installation continues with a note to approve the hook
+inside Codex. Run the installer and Codex with the same `HOME` and `CODEX_HOME`;
+hook approval applies to that profile. If Codex later refreshes the plugin from
+`main` and its contents change, run the installer again to approve the update.
+
 You can also use the following commands to install individually:
 
+### Antigravity
+
+```bash
+agy plugin install https://github.com/postmanlabs/postman-plugin
+```
+
+Run the same command again to update; `agy plugin uninstall postman` removes it.
+In the Antigravity app, **Customizations → Plugins → + Install from URL** takes
+the same URL.
+
 ### Claude Code
 
 [View Postman on Claude Plugins](https://claude.com/plugins/postman)
@@ -48,10 +66,15 @@ does nothing where the marketplace is already registered.
 [View Postman on ChatGPT Plugins](https://chatgpt.com/plugins/postman?open_in_app)
 
 ```bash
-codex plugin marketplace add postmanlabs/postman-plugin
+codex plugin marketplace add postmanlabs/postman-plugin --ref main
+codex plugin marketplace upgrade postman
 codex plugin add postman@postman
 ```
 
+These commands track `main`; review the session-start hook in Codex after a
+manual install. The npx installer also approves the hook after each install or
+update, and moves an existing `codex-release` registration to `main`.
+
 ### Cursor
 
 [View Postman on the Cursor Marketplace](https://cursor.com/marketplace/postman)
@@ -60,6 +83,16 @@ codex plugin add postman@postman
 /add-plugin postman
 ```
 
+### GitHub Copilot CLI
+
+```bash
+copilot plugin marketplace add postmanlabs/postman-plugin
+copilot plugin install postman@postman
+```
+
+`copilot plugin marketplace update postman`, then `copilot plugin update postman`, updates it. Sign in to Postman's MCP server
+with `/mcp` inside a Copilot CLI session.
+
 ### Factory Droid
 
 ```bash
@@ -172,15 +205,19 @@ test consumers without waiting for the real service to be ready or available.
 
 The mock stays local until you choose to push and deploy it. When teammates or
 external systems need access, the same mock can become a durable hosted URL
-without rebuilding it in another tool.
+without rebuilding it in another tool. Pushed to the service's own workspace,
+it's the mock other teams' simulations pull first.
 
 ### Develop against simulated dependencies
 
-The [`api-simulation`](https://github.com/postmanlabs/postman-plugin/blob/main/skills/api-simulation/) skill is the local loop for a
-service change: find every dependency the service calls, mock each one (reusing
-the owning team's mock when they publish one), serve them on one port from one
-`.sim.yaml`, run the real service against them, test, and push. It needs
-Postman CLI 1.70.0 or later:
+The [`api-simulation`](https://github.com/postmanlabs/postman-plugin/blob/main/skills/api-simulation/) skill runs your code (a service
+you're changing, a frontend, a test suite or a demo) for real against stand-ins
+for the HTTP services it calls, served together on one port from one
+`.sim.yaml`. Each stand-in is the owning team's mock when they publish one.
+It reuses an existing `.sim.yaml`, proves a change with a request through the
+changed path, and answers "what happens if X goes down" by running each failure.
+Pushing the simulation is optional and needs your approval. It needs Postman CLI
+1.70.0 or later:
 
 ```bash
 postman simulation run postman/simulations/orders-dev.sim.yaml --port 4900

package/dist/hosts/antigravity.js

@@ -0,0 +1,47 @@
+import { REPO } from '../source.js';
+import { guard, mustProbeJson, mustRun, parseJson } from './shared.js';
+import { result } from './types.js';
+// `agy plugin install` clones a git URL into ~/.gemini/config/plugins/<name>. It has no update
+// command; installing again replaces the copy in place, so a re-run is the update.
+const PLUGIN_NAME = 'postman', SOURCE = `https://github.com/${REPO}`, NEXT = 'Restart Antigravity for the change to take effect.';
+const isOurs = (plugin) => plugin.name === PLUGIN_NAME;
+export const antigravity = {
+    id: 'antigravity',
+    name: 'Antigravity',
+    route: '.antigravity-plugin',
+    async detect(system) {
+        return (await system.which('agy')) !== null;
+    },
+    async status(system) {
+        const exec = await system.probe('agy', ['plugin', 'list', '--json']), plugins = exec.code === 0 ? parseJson(exec.stdout) : null;
+        if (!Array.isArray(plugins)) {
+            return { installed: null, detail: 'could not read `agy plugin list --json`', notes: [] };
+        }
+        const installed = plugins.find(isOurs);
+        if (!installed) {
+            return { installed: false, detail: 'not installed', notes: [] };
+        }
+        return {
+            installed: true,
+            detail: `${PLUGIN_NAME} ${installed.version ?? ''}`.trim(),
+            notes: installed.enabled === false ? ['installed but disabled; run `agy plugin enable postman`'] : []
+        };
+    },
+    install(system) {
+        return guard(async () => {
+            const plugins = await mustProbeJson(system, 'agy', ['plugin', 'list', '--json']), current = plugins.some(isOurs);
+            await mustRun(system, 'agy', ['plugin', 'install', SOURCE]);
+            return result('done', `${current ? 'updated' : 'installed'} ${PLUGIN_NAME}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const plugins = await mustProbeJson(system, 'agy', ['plugin', 'list', '--json']);
+            if (!plugins.some(isOurs)) {
+                return result('skipped', 'not installed');
+            }
+            await mustRun(system, 'agy', ['plugin', 'uninstall', PLUGIN_NAME]);
+            return result('done', `uninstalled ${PLUGIN_NAME}`, NEXT);
+        });
+    }
+};

package/dist/hosts/codex-hooks.js

@@ -0,0 +1,68 @@
+import path from 'node:path';
+export const POSTMAN_HOOK_KEY = 'postman@postman:hooks/codex-hooks.json:session_start:0:0';
+async function postmanHook(rpc, cwd) {
+    const result = await rpc.request('hooks/list', { cwds: [cwd] });
+    if (!Array.isArray(result?.data) || result.data.some((entry) => !Array.isArray(entry.hooks) || entry.errors?.length)) {
+        throw new Error('hooks/list returned no usable hook listing');
+    }
+    const hooks = result.data.flatMap((entry) => entry.hooks).filter((hook) => hook.key === POSTMAN_HOOK_KEY);
+    if (hooks.length > 1) {
+        throw new Error('hooks/list returned more than one Postman session-start hook');
+    }
+    return hooks[0];
+}
+const trustEdit = (hash) => ({
+    edits: [{ keyPath: 'hooks.state', value: { [POSTMAN_HOOK_KEY]: { trusted_hash: hash } }, mergeStrategy: 'upsert' }],
+    reloadUserConfig: true
+});
+/** Approves only Postman's current hook after installation; unsupported APIs never fail the install. */
+export async function approvePostmanHook(system) {
+    const note = (message) => system.log(`  note: ${message}`);
+    let writeAttempted = false;
+    if (system.dryRun) {
+        note('Would inspect and approve Postman\'s current session-start hook after installation through codex app-server:');
+        system.log(`  config/batchWrite ${JSON.stringify(trustEdit('<currentHash from hooks/list>'))}`);
+        return;
+    }
+    try {
+        await system.withJsonRpc('codex', ['app-server'], async (rpc) => {
+            // Version of this small protocol client, independent of the plugin's release.
+            await rpc.request('initialize', { clientInfo: { name: 'postman-plugin-installer', version: '1' } });
+            rpc.notify('initialized');
+            const hook = await postmanHook(rpc, system.cwd);
+            if (!hook) {
+                note('Postman\'s session-start hook was not found; hook approval skipped.');
+                return;
+            }
+            if (hook.trustStatus === 'trusted') {
+                note('Postman\'s Codex session-start hook is already trusted.');
+                return;
+            }
+            if (!['untrusted', 'modified'].includes(hook.trustStatus) || !hook.currentHash || typeof hook.currentHash !== 'string') {
+                throw new Error('Postman\'s hook has an unsupported trust status or hash');
+            }
+            // Confirm the installed instructions are present before approving their hook.
+            const mandateFile = path.resolve(path.dirname(hook.sourcePath), 'session-start-context.md'), mandate = await system.readFile(mandateFile);
+            if (!mandate?.trim()) {
+                throw new Error('could not read the installed hooks/session-start-context.md');
+            }
+            // Startup can refresh marketplaces. A changed hash needs another check,
+            // rather than approving a different version from the one inspected above.
+            const current = await postmanHook(rpc, system.cwd);
+            if (!current || current.currentHash !== hook.currentHash || !['untrusted', 'modified'].includes(current.trustStatus)) {
+                note('Postman\'s hook changed while checking it; approval skipped. Re-run to approve the current version.');
+                return;
+            }
+            writeAttempted = true;
+            await rpc.request('config/batchWrite', trustEdit(hook.currentHash));
+            const after = await postmanHook(rpc, system.cwd);
+            note(after?.trustStatus === 'trusted' && after.currentHash === hook.currentHash ?
+                'Approved Postman\'s Codex session-start hook.' :
+                'Codex accepted the approval write, but the hook is not confirmed trusted. Review it in Codex.');
+        });
+    }
+    catch (error) {
+        // Older Codex releases may lack app-server or hooks/list. Installation still succeeds.
+        note(`Hook approval ${writeAttempted ? 'could not be confirmed' : 'skipped'}: ${error instanceof Error ? error.message : String(error)}. Review the hook in Codex.`);
+    }
+}

package/dist/hosts/codex.js

@@ -1,20 +1,39 @@
-import { REPO, isSameRepo, redact } from '../source.js';
-import { blocked, failed, guard, mustProbeJson, mustRun, parseJson } from './shared.js';
+import { BRANCH, GIT_URL, REPO, isSameRepo, redact } from '../source.js';
+import { StepFailed, blocked, failed, guard, mustProbeJson, mustRun, parseJson } from './shared.js';
 import { result } from './types.js';
+import { approvePostmanHook } from './codex-hooks.js';
 // Codex names the marketplace after `.claude-plugin/marketplace.json`'s `name`.
 // `npx plugins add` installs a second copy under its own `plugins-cli` marketplace.
-const MARKETPLACE = 'postman', PLUGIN_ID = `postman@${MARKETPLACE}`, SHADOW_IDS = ['postman@plugins-cli'], NEXT = 'Restart Codex for the change to take effect.';
+const MARKETPLACE = 'postman', PLUGIN_ID = `postman@${MARKETPLACE}`, LEGACY_REF = 'codex-release', SHADOW_IDS = ['postman@plugins-cli'], NEXT = 'Restart Codex for the change to take effect.';
 function isInstalled(plugins, id) {
     return plugins.some((plugin) => plugin.pluginId === id && plugin.installed !== false);
 }
 async function listPlugins(system) {
     return (await mustProbeJson(system, 'codex', ['plugin', 'list', '--json'])).installed ?? [];
 }
+/** The marketplace's ref as Codex's own config reader reports it; `marketplace list --json` doesn't. */
+export async function registeredRef(system) {
+    const replies = await system.rpc('codex', ['app-server'], [
+        { method: 'initialize', params: { clientInfo: { name: 'postman-plugin', version: '0' } } },
+        { method: 'initialized', notify: true },
+        { method: 'config/read', params: {} }
+    ]), read = replies?.[1]?.result, entry = read?.config?.marketplaces?.[MARKETPLACE];
+    if (!entry || typeof entry !== 'object') {
+        return undefined;
+    }
+    return typeof entry.ref === 'string' ? entry.ref : entry.ref === null || entry.ref === undefined ? null : undefined;
+}
+async function addMarketplace(system) {
+    await mustRun(system, 'codex', ['plugin', 'marketplace', 'add', REPO, '--ref', BRANCH, '--json']);
+    // `add` records no revision, so without this Codex's next startup refetches the plugin and asks for approval again.
+    await mustRun(system, 'codex', ['plugin', 'marketplace', 'upgrade', MARKETPLACE, '--json']);
+}
+/** Adds or upgrades the marketplace, leaving the old release branch for `migrate`. */
 async function refreshMarketplace(system) {
     const listing = await mustProbeJson(system, 'codex', ['plugin', 'marketplace', 'list', '--json']), existing = listing.marketplaces?.find((marketplace) => marketplace.name === MARKETPLACE);
     if (!existing) {
-        await mustRun(system, 'codex', ['plugin', 'marketplace', 'add', REPO, '--json']);
-        return;
+        await addMarketplace(system);
+        return 'ready';
     }
     // A local marketplace can carry any path text, so only a git source counts as this repo.
     const { sourceType, source } = existing.marketplaceSource ?? {};
@@ -22,7 +41,58 @@ async function refreshMarketplace(system) {
         const from = source ? `${sourceType ?? 'unknown'} source ${redact(source)}` : 'an unknown source';
         blocked(`marketplace ${MARKETPLACE} is registered from ${from}, not ${REPO}`);
     }
-    await mustRun(system, 'codex', ['plugin', 'marketplace', 'upgrade', MARKETPLACE, '--json']);
+    if (system.dryRun) {
+        system.log(`  note: Would ask Codex for marketplace ${MARKETPLACE}'s ref: upgrade it on ${BRANCH}, migrate ${LEGACY_REF} to ${BRANCH}, preserve an unreadable ref, or stop for a custom ref. App-server is deferred because its startup can refresh plugins.`);
+        return 'deferred';
+    }
+    const ref = await registeredRef(system);
+    if (ref === undefined) {
+        system.log(`  note: Could not read marketplace ${MARKETPLACE}'s ref through codex app-server; keeping its registration and skipping ref migration.`);
+    }
+    if (ref === BRANCH || ref === null || ref === undefined) {
+        await mustRun(system, 'codex', ['plugin', 'marketplace', 'upgrade', MARKETPLACE, '--json']);
+        return 'ready';
+    }
+    if (ref !== LEGACY_REF) {
+        blocked(`marketplace ${MARKETPLACE} tracks ${ref}, not ${BRANCH}; run \`codex plugin marketplace remove ${MARKETPLACE}\` and re-run`);
+    }
+    return 'legacy';
+}
+/** Re-registers the previous marketplace and its plugin; true when every step exits 0. */
+async function restoreLegacy(system, wasInstalled) {
+    // Exits non-zero when the failed step left nothing registered, which is the state wanted here.
+    await system.run('codex', ['plugin', 'marketplace', 'remove', MARKETPLACE, '--json']);
+    const steps = [['plugin', 'marketplace', 'add', REPO, '--ref', LEGACY_REF, '--json'], ...(wasInstalled ? [['plugin', 'add', PLUGIN_ID, '--json']] : [])];
+    for (const args of steps) {
+        if ((await system.run('codex', args)).code !== 0) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Moves a marketplace registered at the old release branch to main, then adds the plugin. `remove`
+ * uninstalls Postman too, so a failure after it puts the previous registration back.
+ */
+async function migrate(system, wasInstalled) {
+    const reach = await system.probe('git', ['ls-remote', '--exit-code', GIT_URL, `refs/heads/${BRANCH}`]);
+    if (reach.code !== 0) {
+        failed(`can't reach ${BRANCH} in ${REPO}, so marketplace ${MARKETPLACE} was left tracking ${LEGACY_REF}`);
+    }
+    await mustRun(system, 'codex', ['plugin', 'marketplace', 'remove', MARKETPLACE, '--json']);
+    try {
+        await addMarketplace(system);
+        await mustRun(system, 'codex', ['plugin', 'add', PLUGIN_ID, '--json']);
+    }
+    catch (error) {
+        if (!(error instanceof StepFailed)) {
+            throw error;
+        }
+        const restored = await restoreLegacy(system, wasInstalled);
+        failed(`${error.outcome.message}\n${restored ?
+            `restored marketplace ${MARKETPLACE} tracking ${LEGACY_REF}${wasInstalled ? ` and ${PLUGIN_ID}` : ''}` :
+            `could not restore it either; run \`codex plugin marketplace remove ${MARKETPLACE}\`, \`codex plugin marketplace add ${REPO} --ref ${BRANCH}\`, \`codex plugin marketplace upgrade ${MARKETPLACE}\` and \`codex plugin add ${PLUGIN_ID}\``}`);
+    }
 }
 async function removeInstalled(system, plugins, ids) {
     const present = ids.filter((id) => isInstalled(plugins, id));
@@ -44,18 +114,27 @@ export const codex = {
             return { installed: null, detail: 'could not read `codex plugin list --json`', notes: [] };
         }
         const installed = plugins.find((plugin) => plugin.pluginId === PLUGIN_ID && plugin.installed !== false), notes = SHADOW_IDS.filter((id) => isInstalled(plugins, id)).map((id) => `${id} duplicates it and will be removed`);
+        if (installed && await registeredRef(system) === LEGACY_REF) {
+            notes.push(`marketplace ${MARKETPLACE} tracks ${LEGACY_REF} and will be re-added at ${BRANCH}; the installer then approves its session-start hook`);
+        }
         return installed ?
             { installed: true, detail: `${PLUGIN_ID} ${installed.version ?? ''}`.trim(), notes } :
             { installed: false, detail: 'not installed', notes };
     },
     install(system) {
         return guard(async () => {
-            await refreshMarketplace(system);
+            // Listed first: re-registering the marketplace uninstalls its plugins.
             const plugins = await listPlugins(system), wasInstalled = isInstalled(plugins, PLUGIN_ID);
             // `add` is idempotent and is also how Codex updates an installed plugin. It runs
             // before the duplicate is removed, so a failed add still leaves a working copy.
-            await mustRun(system, 'codex', ['plugin', 'add', PLUGIN_ID, '--json']);
+            if (await refreshMarketplace(system) === 'legacy') {
+                await migrate(system, wasInstalled);
+            }
+            else {
+                await mustRun(system, 'codex', ['plugin', 'add', PLUGIN_ID, '--json']);
+            }
             await removeInstalled(system, plugins, SHADOW_IDS);
+            await approvePostmanHook(system);
             return result('done', `${wasInstalled ? 'updated' : 'installed'} ${PLUGIN_ID}`, NEXT);
         });
     },

package/dist/hosts/copilot.js

@@ -0,0 +1,60 @@
+import { REPO } from '../source.js';
+import { guard, mustProbeJson, mustRun, parseJson } from './shared.js';
+import { result } from './types.js';
+// Copilot CLI is deprecating direct installs (repos, URLs, local paths), so this installs from this
+// repo as a marketplace, which Copilot reads from `.claude-plugin/marketplace.json`. Once Postman is
+// listed in awesome-copilot, which Copilot ships registered, `postman@awesome-copilot` replaces it.
+const PLUGIN_NAME = 'postman', MARKETPLACE = 'postman', PLUGIN_ID = `${PLUGIN_NAME}@${MARKETPLACE}`, NEXT = 'Restart Copilot CLI (or run /restart) for the change to take effect.';
+const isOurs = (plugin) => plugin.name === PLUGIN_NAME, 
+// A direct install has no marketplace; it would load the same skills a second time.
+isDirect = (plugin) => isOurs(plugin) && !plugin.marketplace;
+export const copilot = {
+    id: 'copilot',
+    name: 'GitHub Copilot CLI',
+    route: '.github/plugin',
+    async detect(system) {
+        return (await system.which('copilot')) !== null;
+    },
+    async status(system) {
+        const exec = await system.probe('copilot', ['plugin', 'list', '--json']), plugins = exec.code === 0 ? parseJson(exec.stdout) : null;
+        if (!Array.isArray(plugins)) {
+            return { installed: null, detail: 'could not read `copilot plugin list --json`', notes: [] };
+        }
+        const installed = plugins.find(isOurs);
+        if (!installed) {
+            return { installed: false, detail: 'not installed', notes: [] };
+        }
+        return {
+            installed: true,
+            detail: `${PLUGIN_NAME} ${installed.version ?? ''}`.trim(),
+            notes: installed.enabled === false ? ['installed but disabled; run `copilot plugin enable postman`'] : []
+        };
+    },
+    install(system) {
+        return guard(async () => {
+            const plugins = await mustProbeJson(system, 'copilot', ['plugin', 'list', '--json']), marketplaces = await mustProbeJson(system, 'copilot', ['plugin', 'marketplace', 'list', '--json']), current = plugins.some((plugin) => isOurs(plugin) && plugin.marketplace === MARKETPLACE);
+            if (marketplaces.some((marketplace) => marketplace.name === MARKETPLACE)) {
+                await mustRun(system, 'copilot', ['plugin', 'marketplace', 'update', MARKETPLACE]);
+            }
+            else {
+                await mustRun(system, 'copilot', ['plugin', 'marketplace', 'add', REPO]);
+            }
+            // The same name can't be installed twice, so a direct install goes first.
+            if (plugins.some(isDirect)) {
+                await mustRun(system, 'copilot', ['plugin', 'uninstall', PLUGIN_NAME]);
+            }
+            await mustRun(system, 'copilot', current ? ['plugin', 'update', PLUGIN_NAME] : ['plugin', 'install', PLUGIN_ID]);
+            return result('done', `${current ? 'updated' : 'installed'} ${PLUGIN_ID}`, NEXT);
+        });
+    },
+    remove(system) {
+        return guard(async () => {
+            const plugins = await mustProbeJson(system, 'copilot', ['plugin', 'list', '--json']);
+            if (!plugins.some(isOurs)) {
+                return result('skipped', 'not installed');
+            }
+            await mustRun(system, 'copilot', ['plugin', 'uninstall', PLUGIN_NAME]);
+            return result('done', `uninstalled ${PLUGIN_NAME}`, NEXT);
+        });
+    }
+};

package/dist/hosts/index.js

@@ -1,8 +1,10 @@
+import { antigravity } from './antigravity.js';
 import { claudeCode } from './claude-code.js';
 import { codex } from './codex.js';
+import { copilot } from './copilot.js';
 import { cursor } from './cursor.js';
 import { factory } from './factory.js';
 import { kimi } from './kimi.js';
 import { opencode } from './opencode.js';
 import { pi } from './pi.js';
-export const HOSTS = [claudeCode, codex, cursor, factory, kimi, opencode, pi];
+export const HOSTS = [antigravity, claudeCode, codex, copilot, cursor, factory, kimi, opencode, pi];

package/dist/json-rpc.js

@@ -0,0 +1,113 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+export class JsonRpcError extends Error {
+    reply;
+    constructor(reply) {
+        super(`app-server RPC error ${reply.code ?? ''}: ${reply.message ?? 'unknown error'}`);
+        this.reply = reply;
+    }
+}
+/** One stdio session with a deadline for each request. */
+export async function withJsonRpc(file, args, env, use, timeoutMs) {
+    // npm's Windows launchers need cmd.exe, just as System.run's launchers do.
+    const quote = (arg) => /^[\w@./:=-]+$/.test(arg) ? arg : `"${arg}"`, shell = /\.(cmd|bat)$/i.test(file), child = shell ?
+        spawn(quote(file), args.map(quote), { env, shell: true, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }) :
+        spawn(file, args, { env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }), lines = createInterface({ input: child.stdout }), pending = new Map();
+    let nextId = 0, failure;
+    function fail(error) {
+        failure = error;
+        for (const entry of pending.values()) {
+            clearTimeout(entry.timer);
+            entry.reject(error);
+        }
+        pending.clear();
+    }
+    child.on('error', fail);
+    child.stdin.on('error', fail);
+    // Drain diagnostics without putting arbitrary app-server output into installer logs.
+    child.stderr.resume();
+    const closed = new Promise((resolve) => child.once('close', (code) => {
+        fail(new Error(`app-server closed (exit ${code ?? 'signal'})`));
+        resolve();
+    }));
+    lines.on('line', (line) => {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            fail(new Error('app-server returned invalid JSON'));
+            return;
+        }
+        // Notifications are not replies. A server request is unsupported by this client.
+        if (message && typeof message.method === 'string') {
+            if (message.id !== undefined) {
+                child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: message.id, error: { code: -32601, message: 'Method not found' } }) + '\n');
+            }
+            return;
+        }
+        const entry = pending.get(message?.id);
+        if (!entry) {
+            return;
+        }
+        clearTimeout(entry.timer);
+        pending.delete(message.id);
+        if (message.error) {
+            entry.reject(new JsonRpcError(message.error));
+        }
+        else if ('result' in message) {
+            entry.resolve(message.result);
+        }
+        else {
+            entry.reject(new Error('app-server reply has no result'));
+        }
+    });
+    try {
+        return await use({
+            request(method, params) {
+                if (failure) {
+                    return Promise.reject(failure);
+                }
+                const id = ++nextId;
+                return new Promise((resolve, reject) => {
+                    const timer = setTimeout(() => fail(new Error(`app-server timed out waiting for ${method}`)), timeoutMs);
+                    pending.set(id, { resolve: (value) => resolve(value), reject, timer });
+                    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+                });
+            },
+            notify(method, params) {
+                if (failure) {
+                    throw failure;
+                }
+                child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method, params }) + '\n');
+            }
+        });
+    }
+    finally {
+        fail(new Error('app-server session ended'));
+        lines.close();
+        child.stdin.end();
+        if (child.exitCode === null && child.signalCode === null) {
+            if (shell && process.platform === 'win32' && child.pid) {
+                // Killing cmd.exe alone leaves its Codex child holding the pipes open.
+                spawn('taskkill', ['/pid', String(child.pid), '/t', '/f'], { stdio: 'ignore', windowsHide: true }).on('error', () => child.kill());
+            }
+            else {
+                child.kill();
+            }
+        }
+        let force;
+        const forced = new Promise((resolve) => {
+            force = setTimeout(() => {
+                child.kill('SIGKILL');
+                // A descendant retaining a pipe must not hold the installer open.
+                child.stdin.destroy();
+                child.stdout.destroy();
+                child.stderr.destroy();
+                resolve();
+            }, 1000);
+        });
+        await Promise.race([closed, forced]);
+        clearTimeout(force);
+    }
+}

package/dist/system.js

@@ -3,6 +3,7 @@ import fs from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
 import { redact } from './source.js';
+import { JsonRpcError, withJsonRpc } from './json-rpc.js';
 // A missing file, or a path through something that isn't a directory. Anything else,
 // such as a file that exists but can't be read, must not pass for "absent".
 const ABSENT = ['ENOENT', 'ENOTDIR'];
@@ -35,8 +36,8 @@ function execute(file, args, env) {
 export function formatCommand(command, args) {
     return [command, ...args].map((part) => redact(part)).map((part) => (/^[\w@./:=~-]+$/.test(part) ? part : JSON.stringify(part))).join(' ');
 }
-export function createSystem({ dryRun = false, log = (line) => console.log(line) } = {}) {
-    const env = process.env, platform = process.platform;
+export function createSystem({ dryRun = false, log = (line) => console.log(line), env = process.env, home = os.homedir(), cwd = process.cwd() } = {}) {
+    const platform = process.platform;
     async function which(command) {
         const extensions = platform === 'win32' ? (env.PATHEXT || '.EXE;.CMD;.BAT').split(';') : [''];
         for (const dir of (env.PATH || '').split(path.delimiter).filter(Boolean)) {
@@ -59,10 +60,11 @@ export function createSystem({ dryRun = false, log = (line) => console.log(line)
         return (await which(command)) || command;
     }
     return {
-        home: os.homedir(),
+        home,
         platform,
         env,
         dryRun,
+        cwd,
         which,
         async exists(file) {
             try {
@@ -101,6 +103,35 @@ export function createSystem({ dryRun = false, log = (line) => console.log(line)
         async probe(command, args) {
             return execute(await resolve(command), args, env);
         },
+        async rpc(command, args, calls) {
+            if (dryRun) {
+                return null;
+            }
+            try {
+                return await withJsonRpc(await resolve(command), args, env, async (rpc) => {
+                    const replies = [];
+                    for (const call of calls) {
+                        if (call.notify) {
+                            rpc.notify(call.method, call.params);
+                            continue;
+                        }
+                        try {
+                            replies.push({ result: await rpc.request(call.method, call.params) });
+                        }
+                        catch (error) {
+                            if (!(error instanceof JsonRpcError)) {
+                                throw error;
+                            }
+                            replies.push({ error: error.reply });
+                        }
+                    }
+                    return replies;
+                }, 30000);
+            }
+            catch {
+                return null;
+            }
+        },
         async run(command, args, options = {}) {
             log(`  $ ${formatCommand(command, args)}`);
             if (dryRun) {
@@ -108,6 +139,12 @@ export function createSystem({ dryRun = false, log = (line) => console.log(line)
             }
             return execute(await resolve(command), args, { ...env, ...options.env });
         },
+        async withJsonRpc(command, args, use, timeoutMs = 15000) {
+            log(`  $ ${formatCommand(command, args)} (stdio RPC)`);
+            if (!dryRun) {
+                return withJsonRpc(await resolve(command), args, env, use, timeoutMs);
+            }
+        },
         async writeFile(file, content) {
             log(`  write ${file}`);
             if (!dryRun) {

package/mcp.pi.json

@@ -6,8 +6,8 @@
       "description": "Postman workspaces, collections, specs, environments, mocks and monitors",
       "headers": {
         "X-Source": "postman-pi-plugin",
-        "X-Plugin-Version": "0.3.0",
-        "User-Agent": "postman-pi-plugin/0.3.0"
+        "X-Plugin-Version": "0.4.1-rc.0",
+        "User-Agent": "postman-pi-plugin/0.4.1-rc.0"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/postman-plugin",
-  "version": "0.3.0",
+  "version": "0.4.1-rc.0",
   "description": "Postman's API engineering skills for coding agents: a Pi package, and an npx installer that sets up Claude Code, Codex, Cursor, Kimi Code, Factory Droid, OpenCode and Pi.",
   "type": "module",
   "license": "Apache-2.0",