agent-permission 0.1.5 → 0.1.6

package/README.md

@@ -5,7 +5,7 @@ Give AI agents a permission gate before they touch external URLs.
 ## Quickstart
 
 ```bash
-npx agent-permission install --adapter auto
+npx -y agent-permission@latest install --adapter auto
 ```
 
 This adds an Agent Permission block to the local agent instruction file, such as `AGENTS.md`, `CLAUDE.md`, or `agent-permission.chatgpt.md`, depending on the selected adapter. It also writes a tiny project-local runner at `.agent-permission/agent-permission.mjs` so repeated checks do not need npm registry access.
@@ -13,7 +13,13 @@ This adds an Agent Permission block to the local agent instruction file, such as
 To install instructions and configure live checks in one step:
 
 ```bash
-npx agent-permission install --adapter auto --api-key <YOUR_API_KEY>
+npx -y agent-permission@latest install --adapter auto --api-key <YOUR_API_KEY>
+```
+
+To avoid installing a project runner in every repository, install once at user scope:
+
+```bash
+npx -y agent-permission@latest install --adapter codex --scope user
 ```
 
 Add an API key when you want live checks from the command line, CI, or agent runs:
@@ -31,19 +37,21 @@ After install, project instructions tell compatible agents to run:
 node .agent-permission/agent-permission.mjs check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
 ```
 
-If the local runner is missing, the installed instructions tell the agent to use npm as a fallback:
+If the runner is missing, the installed instructions tell the agent to stop and ask you to repair the installation once:
 
 ```bash
-npx -y agent-permission@latest check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
+npx -y agent-permission@latest install --adapter auto --scope project
 ```
 
+The generated preflight block does not tell agents to run `npx ... check` during a URL request, so repeated checks do not need registry access or unpinned-code approval.
+
 ## Commands
 
 ```bash
 agent-permission check <url> --action <crawl|summarize|extract|train|transact|post>
 agent-permission batch --file checks.json
 agent-permission verify-receipt --file receipt.json
-agent-permission install --adapter auto|codex|claude|chatgpt|openclaw [--api-key <key>]
+agent-permission install --adapter auto|codex|claude|chatgpt|openclaw [--scope project|user] [--api-key <key>]
 agent-permission config set api-key <key>
 agent-permission config doctor
 ```

package/dist/install.d.ts

@@ -7,5 +7,5 @@ export interface InstallResult {
 }
 export declare function installAgentInstructions(adapter: Adapter, scope: InstallScope, runtime: Runtime): Promise<InstallResult>;
 export declare function upsertBlock(existing: string, blockBody: string): string;
-export declare function buildInstructionBlock(adapter: Exclude<Adapter, 'auto'>, runnerCommand?: string): string;
+export declare function buildInstructionBlock(adapter: Exclude<Adapter, 'auto'>, runnerCommand?: string, repairCommand?: string): string;
 //# sourceMappingURL=install.d.ts.map

package/dist/install.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAmB,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAM7E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAgB9H;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAU9D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,EAAE,aAAa,SAAgC,UA2BrH"}
+{"version":3,"file":"install.d.ts","sourceRoot":"","sources":["../src/install.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,OAAO,EAAmB,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAM7E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAiB9H;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAU9D;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,EACjC,aAAa,SAAgC,EAC7C,aAAa,SAAgF,UA4B9F"}

package/dist/install.js

@@ -9,14 +9,15 @@ export async function installAgentInstructions(adapter, scope, runtime) {
     const path = getInstructionPath(resolved, scope, runtime);
     const runner = getRunnerPath(scope, runtime);
     const runnerCommand = getRunnerCommand(scope, runner);
+    const repairCommand = getRepairCommand(resolved, scope);
     const existing = await readFile(path, 'utf8').catch((err) => {
         if (err && typeof err === 'object' && 'code' in err && err.code === 'ENOENT')
             return '';
         throw err;
     });
-    const next = upsertBlock(existing, buildInstructionBlock(resolved, runnerCommand));
+    const next = upsertBlock(existing, buildInstructionBlock(resolved, runnerCommand, repairCommand));
     await mkdir(dirname(path), { recursive: true });
-    await writeLocalRunner(runner);
+    await writeLocalRunner(runner, runnerCommand);
     await writeFile(path, next);
     return { adapter: resolved, path, runnerPath: runner, runnerCommand };
 }
@@ -29,7 +30,7 @@ export function upsertBlock(existing, blockBody) {
     const prefix = existing.trimEnd();
     return prefix ? `${prefix}\n\n${block}\n` : `${block}\n`;
 }
-export function buildInstructionBlock(adapter, runnerCommand = `node ${PROJECT_RUNNER_PATH}`) {
+export function buildInstructionBlock(adapter, runnerCommand = `node ${PROJECT_RUNNER_PATH}`, repairCommand = `npx -y agent-permission@latest install --adapter ${adapter} --scope project`) {
     const agentName = {
         codex: 'Codex',
         claude: 'Claude',
@@ -46,10 +47,10 @@ Before crawling, summarizing, extracting, training on, transacting with, or post
 ${runnerCommand} check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
 \`\`\`
 
-If the local runner is missing, run the same check through npm:
+Do not use npm while handling an individual URL request. If the runner command is missing or cannot start, stop and ask the user to repair the installation once with:
 
 \`\`\`bash
-npx -y agent-permission@latest check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
+${repairCommand}
 \`\`\`
 
 Use \`crawl\` for fetching or indexing pages, \`summarize\` for compacting page content, \`extract\` for structured data pulls, \`train\` for model training or dataset creation, \`transact\` for purchase/account-changing actions, and \`post\` for creating or modifying remote content.
@@ -97,9 +98,12 @@ function getRunnerCommand(scope, runnerPath) {
     }
     return `node ${PROJECT_RUNNER_PATH}`;
 }
-async function writeLocalRunner(path) {
+function getRepairCommand(adapter, scope) {
+    return `npx -y agent-permission@latest install --adapter ${adapter} --scope ${scope}`;
+}
+async function writeLocalRunner(path, runnerCommand) {
     await mkdir(dirname(path), { recursive: true });
-    await writeFile(path, buildLocalRunner(), { mode: 0o644 });
+    await writeFile(path, buildLocalRunner(runnerCommand), { mode: 0o644 });
 }
 function shellQuote(value) {
     return `'${value.replace(/'/g, `'\\''`)}'`;
@@ -123,13 +127,14 @@ function isOpenClawInstructions(content) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-function buildLocalRunner() {
+function buildLocalRunner(runnerCommand = `node ${PROJECT_RUNNER_PATH}`) {
     return `#!/usr/bin/env node
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
 import { homedir } from 'node:os';
 
 const DEFAULT_API_URL = '${DEFAULT_API_URL}';
+const RUNNER_COMMAND = ${JSON.stringify(runnerCommand)};
 const ACTIONS = ['crawl', 'summarize', 'extract', 'train', 'transact', 'post'];
 
 const code = await main(process.argv.slice(2)).catch((err) => {
@@ -211,7 +216,7 @@ async function runConfig(args) {
 
 async function checkPermission(params, options) {
   if (!options.apiKey) {
-    throw new Error('Missing API key. Set AGENT_PERMISSION_API_KEY or run \`node .agent-permission/agent-permission.mjs config set api-key <key>\`.');
+    throw new Error(\`Missing API key. Set AGENT_PERMISSION_API_KEY or run \\\`\${RUNNER_COMMAND} config set api-key <key>\\\`.\`);
   }
 
   const apiUrl = trimSlash(options.apiUrl);
@@ -380,9 +385,9 @@ function helpText() {
   return \`Agent Permission local runner
 
 Usage:
-  node .agent-permission/agent-permission.mjs check <url> --action <action> [--json] [--exit-code]
-  node .agent-permission/agent-permission.mjs config set api-key <key>
-  node .agent-permission/agent-permission.mjs config doctor
+  \${RUNNER_COMMAND} check <url> --action <action> [--json] [--exit-code]
+  \${RUNNER_COMMAND} config set api-key <key>
+  \${RUNNER_COMMAND} config doctor
 
 Actions:
   crawl, summarize, extract, train, transact, post

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-permission",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Public CLI for Agent Permission checks and agent workspace installation.",
   "type": "module",
   "bin": "./dist/index.js",