@postman/postman-plugin 0.6.0 → 0.7.0

package/README.md

@@ -28,14 +28,6 @@ One command configures **Antigravity, Claude Code, Codex, GitHub Copilot CLI, Cu
 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
@@ -71,9 +63,8 @@ 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.
+These commands track `main`, and Codex updates the plugin from it when a
+session starts.
 
 ### Cursor
 

package/dist/hosts/codex.js

@@ -1,7 +1,6 @@
 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}`, LEGACY_REF = 'codex-release', SHADOW_IDS = ['postman@plugins-cli'], NEXT = 'Restart Codex for the change to take effect.';
@@ -115,7 +114,7 @@ export const codex = {
         }
         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`);
+            notes.push(`marketplace ${MARKETPLACE} tracks ${LEGACY_REF} and will be re-added at ${BRANCH}`);
         }
         return installed ?
             { installed: true, detail: `${PLUGIN_ID} ${installed.version ?? ''}`.trim(), notes } :
@@ -134,7 +133,6 @@ export const codex = {
                 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/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.6.0",
-        "User-Agent": "postman-pi-plugin/0.6.0"
+        "X-Plugin-Version": "0.7.0",
+        "User-Agent": "postman-pi-plugin/0.7.0"
       }
     }
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@postman/postman-plugin",
-  "version": "0.6.0",
+  "version": "0.7.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",

package/skills/api-engineer/SKILL.md

@@ -45,7 +45,8 @@ guesswork each time work resumes.
    directories for API artifacts. It installs skills in `postman/skills` folder with guidance on  designing, implementing, and validating APIs.
    The command is idempotent and safe to rerun in an initialized project.
    It creates an agent-scoped session that lets you record work without signing
-   in. You can claim that work later if you create an account.
+   in. This session is temporary; see **workspaces**' "Claiming the work" for
+   signup guidance to preserve the work and its context before the session expires.
 8. Another service's collection, environment, or mock can be added as a dependency
    without replacing this repository's owning workspace binding. Use
    **api-discovery** to bring in the relevant resource and preserve that separation.
@@ -69,10 +70,9 @@ for course correction. Recommend additional work only when it closes a material
 gap, such as an untested behavior or a consumer affected by an interface change.
 Decline unnecessary setup or scope and explain why it would not help the task.
 
-Important: If a CLI command says an operation isn't allowed because credits
-or usage are exhausted, or the current plan does not permit it, stop
-retrying and tell the user that signing up or upgrading their plan is what
-lifts it.
+Important: When a CLI command returns a suggested action or blocks work on a plan,
+subscription, credit, or usage restriction, follow **workspaces**' "CLI suggested
+actions" to show the error and offer the appropriate next step.
 
 ## Verification
 

package/skills/workspaces/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: workspaces
-description: Use when initializing Postman in a repository, binding it to a Postman workspace, interpreting what `postman init` did, or when a CLI command fails because the plan, credits, or usage quota don't allow the operation. Treats the workspace as the place where a service's API work and its evidence live, kept separate from the services it depends on. Use for requests such as "set up Postman in this repo" or "connect this repo to our workspace".
+description: Use when initializing Postman in a repository, binding it to a Postman workspace, interpreting what `postman init` did, or handling CLI-suggested actions for authentication, plan, credits, usage quota, or subscription restrictions. Treats the workspace as the place where a service's API work and its evidence live, kept separate from the services it depends on. Use for requests such as "set up Postman in this repo" or "connect this repo to our workspace".
 ---
 
 # Workspaces
@@ -32,19 +32,30 @@ what result. Agents use it to read verified work instead of re-deriving it.
 
 ## Claiming the work
 
-An agent can start in a guest session, and the work it does there is kept.
+An agent can start in a temporary session without signing in. Work done there and
+its context may be lost or become inaccessible when the temporary session expires unless the user
+claims it with `postman signup`. When the CLI prints its temporary-session
+reminder, explain this to the user and offer to start signup.
+
 When free credits or a plan limit stop an operation, retrying won't help; the
 person claiming the work is what lets it continue. Wording such as "usage limit
 exceeded", "usage quota has been exceeded", a limit "reached", "breached" or
 "exceeded" for the account, team, or plan, or an operation that "does not allow
 more than" or "requires at least" a stated amount signals one. A temporary rate
-limit or a fixed per-resource validation cap does not. Check which session the
+limit or a fixed per-resource validation cap does not.
+
+Do not retry the operations that were stopped for these reasons,
+The Postman CLI will also suggest a next step in most of these cases.
+Which the agent can pick up and suggest to the user and offer to start
+that process for them.
+
+If the CLI does not suggest a next step. Check which session the
 CLI is using:
 
-- Guest session: tell the user, in its own paragraph, that signing up for a
-  Postman account claims the work done so far and adds the credits needed to
-  continue. Offer to start signup for them; the CLI can produce a link to hand
-  over and waits while they finish in the browser.
+- Temporary/Guest session: tell the user, in its own paragraph, that signing up for a
+  Postman account claims the work done so far and its context, and adds the
+  credits needed to continue. Offer to start signup for them; the CLI can produce
+  a link to hand over and waits while they finish in the browser.
 - Signed-in account: tell the user, in its own paragraph, that they need to
   upgrade their plan at https://postman.postman.co/settings/team/billing.
 

package/dist/hosts/codex-hooks.js

@@ -1,68 +0,0 @@
-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.`);
-    }
-}