agent-permission 0.1.4 → 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/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE7G,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,MAAM,EAAE,MAAM,CAAC;gBAEH,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAetG;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAexH;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAUnH"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,WAAW,EAAE,aAAa,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAE7G,UAAU,UAAU;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,OAAO,KAAK,CAAC;CACrB;AAED,qBAAa,uBAAwB,SAAQ,KAAK;IAChD,MAAM,EAAE,MAAM,CAAC;gBAEH,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK5C;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAgBtG;AAED,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,SAAS,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC;IAAE,OAAO,EAAE,aAAa,EAAE,CAAA;CAAE,CAAC,CAgBxH;AAED,wBAAsB,aAAa,CAAC,OAAO,EAAE,iBAAiB,EAAE,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,qBAAqB,CAAC,CAWnH"}

package/dist/api.js

@@ -10,7 +10,8 @@ export async function checkPermission(params, options) {
     if (!options.apiKey) {
         throw new AgentPermissionApiError(401, 'Missing API key. Set AGENT_PERMISSION_API_KEY or run `agent-permission config set api-key <key>`.');
     }
-    const res = await options.fetch(`${trimSlash(options.apiUrl)}/v1/check`, {
+    const apiUrl = trimSlash(options.apiUrl);
+    const res = await fetchApi(apiUrl, '/v1/check', options.fetch, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -24,7 +25,8 @@ export async function batchCheckPermissions(batch, options) {
     if (!options.apiKey) {
         throw new AgentPermissionApiError(401, 'Missing API key. Set AGENT_PERMISSION_API_KEY or run `agent-permission config set api-key <key>`.');
     }
-    const res = await options.fetch(`${trimSlash(options.apiUrl)}/v1/batch-check`, {
+    const apiUrl = trimSlash(options.apiUrl);
+    const res = await fetchApi(apiUrl, '/v1/batch-check', options.fetch, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -35,7 +37,8 @@ export async function batchCheckPermissions(batch, options) {
     return readResponse(res);
 }
 export async function verifyReceipt(receipt, options) {
-    const res = await options.fetch(`${trimSlash(options.apiUrl)}/v1/verify-receipt`, {
+    const apiUrl = trimSlash(options.apiUrl);
+    const res = await fetchApi(apiUrl, '/v1/verify-receipt', options.fetch, {
         method: 'POST',
         headers: {
             'Content-Type': 'application/json',
@@ -44,6 +47,19 @@ export async function verifyReceipt(receipt, options) {
     });
     return readResponse(res);
 }
+async function fetchApi(apiUrl, path, fetchImpl, init) {
+    try {
+        return await fetchImpl(`${apiUrl}${path}`, init);
+    }
+    catch (err) {
+        const detail = err instanceof Error && err.message ? ` (${err.message})` : '';
+        throw new AgentPermissionApiError(0, [
+            `Agent Permission API request failed before reaching the service${detail}.`,
+            `Check network access to ${apiUrl}.`,
+            'In sandboxed agents, approve outbound network access and retry.',
+        ].join('\n'));
+    }
+}
 async function readResponse(res) {
     const body = await res.json().catch(() => ({}));
     if (!res.ok) {

package/dist/cli.js

@@ -18,15 +18,15 @@ export async function runCli(argv, runtime, io) {
             return 0;
         }
         if (command === 'check')
-            return runCheck(rest, runtime, io);
+            return await runCheck(rest, runtime, io);
         if (command === 'batch')
-            return runBatch(rest, runtime, io);
+            return await runBatch(rest, runtime, io);
         if (command === 'verify-receipt')
-            return runVerify(rest, runtime, io);
+            return await runVerify(rest, runtime, io);
         if (command === 'install')
-            return runInstall(rest, runtime, io);
+            return await runInstall(rest, runtime, io);
         if (command === 'config')
-            return runConfig(rest, runtime, io);
+            return await runConfig(rest, runtime, io);
         io.stderr(`Unknown command: ${command}\n\n${helpText()}`);
         return 1;
     }

package/dist/format.d.ts

@@ -1,5 +1,5 @@
 import { CheckResponse, VerifyReceiptResponse } from './types.js';
-export declare function decisionExitCode(decision: string): 2 | 0 | 3 | 1;
+export declare function decisionExitCode(decision: string): 0 | 2 | 3 | 1;
 export declare function formatCheckHuman(result: CheckResponse): string;
 export declare function formatBatchHuman(results: CheckResponse[]): string;
 export declare function formatVerifyHuman(result: VerifyReceiptResponse): string;

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,21 +216,35 @@ 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 res = await fetch(\`\${trimSlash(options.apiUrl)}/v1/check\`, {
-    method: 'POST',
-    headers: {
-      'Content-Type': 'application/json',
-      'Authorization': \`Bearer \${options.apiKey}\`,
-    },
-    body: JSON.stringify(params),
-  });
+  const apiUrl = trimSlash(options.apiUrl);
+  const res = await fetchApi(apiUrl, '/v1/check', {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': \`Bearer \${options.apiKey}\`,
+      },
+      body: JSON.stringify(params),
+    });
 
   return readResponse(res);
 }
 
+async function fetchApi(apiUrl, path, init) {
+  try {
+    return await fetch(\`\${apiUrl}\${path}\`, init);
+  } catch (err) {
+    const detail = err instanceof Error && err.message ? \` (\${err.message})\` : '';
+    throw new Error([
+      \`Agent Permission API request failed before reaching the service\${detail}.\`,
+      \`Check network access to \${apiUrl}.\`,
+      'In sandboxed agents, approve outbound network access and retry.',
+    ].join('\\n'));
+  }
+}
+
 async function readResponse(res) {
   const body = await res.json().catch(() => ({}));
   if (!res.ok) {
@@ -366,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.4",
+  "version": "0.1.6",
   "description": "Public CLI for Agent Permission checks and agent workspace installation.",
   "type": "module",
   "bin": "./dist/index.js",