agent-permission 0.1.6 → 0.1.7

package/README.md

@@ -4,8 +4,20 @@ Give AI agents a permission gate before they touch external URLs.
 
 ## Quickstart
 
+For one personal Codex setup that works across repositories:
+
+```bash
+npx -y agent-permission@latest install --adapter codex
+node "$HOME/.config/agent-permission/agent-permission.mjs" config set api-key <YOUR_API_KEY>
+node "$HOME/.config/agent-permission/agent-permission.mjs" config doctor
+```
+
+`install --adapter codex` defaults to user scope, writes personal Codex instructions under your Agent Permission config directory, and installs a reusable runner there. The install output prints the exact runner command for your machine.
+
+For a repository-owned instruction block:
+
 ```bash
-npx -y agent-permission@latest install --adapter auto
+npx -y agent-permission@latest install --adapter auto --scope project
 ```
 
 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,20 +25,20 @@ 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 -y agent-permission@latest install --adapter auto --api-key <YOUR_API_KEY>
+npx -y agent-permission@latest install --adapter codex --api-key <YOUR_API_KEY>
 ```
 
-To avoid installing a project runner in every repository, install once at user scope:
+To force a project-local Codex install instead:
 
 ```bash
-npx -y agent-permission@latest install --adapter codex --scope user
+npx -y agent-permission@latest install --adapter codex --scope project
 ```
 
 Add an API key when you want live checks from the command line, CI, or agent runs:
 
 ```bash
-node .agent-permission/agent-permission.mjs config set api-key <YOUR_API_KEY>
-node .agent-permission/agent-permission.mjs check https://example.com/blog-post --action summarize --exit-code
+node "$HOME/.config/agent-permission/agent-permission.mjs" config set api-key <YOUR_API_KEY>
+node "$HOME/.config/agent-permission/agent-permission.mjs" check https://example.com/blog-post --action summarize --exit-code
 ```
 
 ## What the Agent Runs
@@ -34,16 +46,16 @@ node .agent-permission/agent-permission.mjs check https://example.com/blog-post
 After install, project instructions tell compatible agents to run:
 
 ```bash
-node .agent-permission/agent-permission.mjs check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
+node <installed-runner-path> check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
 ```
 
 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 install --adapter auto --scope project
+npx -y agent-permission@latest install --adapter codex --scope user
 ```
 
-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.
+If the API key is missing, the generated instructions tell the agent to stop and ask you to run the exact `config set api-key` command for that installed runner. 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
 

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAKA,OAAO,EAAyD,KAAK,EAAuD,OAAO,EAAE,MAAM,YAAY,CAAC;AAExJ,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BzF;AAmID,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CA2BtD"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"AAKA,OAAO,EAAyD,KAAK,EAAuD,OAAO,EAAE,MAAM,YAAY,CAAC;AAExJ,UAAU,WAAW;IACnB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IACxC,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,OAAO,EAAE,EAAE,EAAE,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CA6BzF;AA6ID,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CA2BtD"}

package/dist/cli.js

@@ -8,7 +8,7 @@ export async function runCli(argv, runtime, io) {
     const invoked = argv[1] || 'agent-permission';
     const args = argv.slice(2);
     if (isSkillsInvocation(invoked, args)) {
-        return runCli([argv[0], argv[1], 'install', '--adapter', 'auto'], runtime, io);
+        return runCli([argv[0], argv[1], 'install', '--adapter', 'codex', '--scope', 'user'], runtime, io);
     }
     const command = args[0];
     const rest = args.slice(1);
@@ -42,7 +42,14 @@ async function runCheck(args, runtime, io) {
     if (!url || !action) {
         throw new Error('Usage: agent-permission check <url> --action <crawl|summarize|extract|train|transact|post>');
     }
+    const localDecision = localUrlDecision(url, action);
+    if (localDecision) {
+        const format = outputFormat(parsed);
+        io.stdout(format === 'json' ? JSON.stringify(localDecision, null, 2) : formatCheckHuman(localDecision));
+        return parsed.flags['exit-code'] ? decisionExitCode(localDecision.decision) : 0;
+    }
     const config = await resolveConfig(runtime);
+    ensureApiKeyConfigured(config.apiKey, invokedRunnerCommand(runtime));
     const params = {
         url,
         action,
@@ -66,6 +73,7 @@ async function runBatch(args, runtime, io) {
         throw new Error('Usage: agent-permission batch --file checks.json');
     }
     const config = await resolveConfig(runtime);
+    ensureApiKeyConfigured(config.apiKey, invokedRunnerCommand(runtime));
     const batch = JSON.parse(await readFile(file, 'utf8'));
     const result = await batchCheckPermissions(batch, {
         apiUrl: stringFlag(parsed, 'api-url') || config.apiUrl,
@@ -98,11 +106,12 @@ async function runVerify(args, runtime, io) {
 async function runInstall(args, runtime, io) {
     const parsed = parseFlags(args);
     const adapter = parseAdapter(stringFlag(parsed, 'adapter') || parsed.positionals[0] || 'auto');
-    const scope = parseScope(stringFlag(parsed, 'scope') || 'project');
+    const scope = parseScope(stringFlag(parsed, 'scope') || defaultInstallScope(adapter));
     const result = await installAgentInstructions(adapter, scope, runtime);
     const messages = [
         `Installed Agent Permission instructions for ${result.adapter} at ${result.path}`,
         `Installed local Agent Permission runner at ${result.runnerPath}`,
+        `Agent preflight command: ${result.checkCommand}`,
     ];
     const apiKey = stringFlag(parsed, 'api-key');
     if (apiKey) {
@@ -113,7 +122,7 @@ async function runInstall(args, runtime, io) {
     else {
         const config = await resolveConfig(runtime);
         if (!config.apiKey) {
-            messages.push(`API key is not configured. Live checks will fail until you run \`${result.runnerCommand} config set api-key <YOUR_API_KEY>\` or set AGENT_PERMISSION_API_KEY.`, `Verify setup with \`${result.runnerCommand} config doctor\`.`);
+            messages.push(`API key is not configured. Live checks will fail until you run \`${result.apiKeyCommand}\` or set AGENT_PERMISSION_API_KEY.`, `Verify setup with \`${result.doctorCommand}\`.`);
         }
     }
     io.stdout(messages.join('\n'));
@@ -197,6 +206,89 @@ function parseScope(value) {
         return value;
     throw new Error('Scope must be project or user.');
 }
+function ensureApiKeyConfigured(apiKey, runnerCommand) {
+    if (!apiKey) {
+        throw new Error(`Missing API key. Set AGENT_PERMISSION_API_KEY or run \`${runnerCommand} config set api-key <key>\`.`);
+    }
+}
+function invokedRunnerCommand(runtime) {
+    return runtime.env.AGENT_PERMISSION_RUNNER_COMMAND || 'agent-permission';
+}
+function defaultInstallScope(adapter) {
+    return adapter === 'codex' ? 'user' : 'project';
+}
+function localUrlDecision(url, action) {
+    const localKind = localUrlKind(url);
+    if (!localKind)
+        return undefined;
+    const issuedAt = new Date().toISOString();
+    return {
+        id: 'local_url_check',
+        decision: 'allow',
+        confidence: 'high',
+        risk: 'low',
+        reasons: [
+            `${localKind} URL was not sent to the Agent Permission API; local development and in-app browser URLs are allowed without external preflight.`,
+        ],
+        sources: [
+            {
+                type: 'local_url',
+                url,
+                fetched_at: issuedAt,
+                evidence: localKind,
+            },
+        ],
+        receipt: {
+            receipt_id: 'local_only_no_external_receipt',
+            check_id: 'local_url_check',
+            url_hash: 'local_only',
+            action,
+            decision: 'allow',
+            source_hashes: [],
+            issued_at: issuedAt,
+            account_id: 'local',
+            signature_alg: 'none',
+            signature: 'not_signed',
+        },
+    };
+}
+function localUrlKind(value) {
+    let parsed;
+    try {
+        parsed = new URL(value);
+    }
+    catch {
+        return undefined;
+    }
+    if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:')
+        return undefined;
+    const hostname = parsed.hostname.toLowerCase().replace(/^\[|\]$/g, '');
+    if (hostname === 'localhost' || hostname.endsWith('.localhost'))
+        return 'localhost';
+    if (hostname === '::1')
+        return 'loopback';
+    if (hostname.startsWith('127.'))
+        return 'loopback';
+    if (hostname === '0.0.0.0')
+        return 'local bind address';
+    if (hostname.endsWith('.local'))
+        return 'local network';
+    const parts = hostname.split('.').map((part) => Number(part));
+    if (parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)) {
+        const [first, second] = parts;
+        if (first === 10)
+            return 'private network';
+        if (first === 172 && second >= 16 && second <= 31)
+            return 'private network';
+        if (first === 192 && second === 168)
+            return 'private network';
+        if (first === 169 && second === 254)
+            return 'link-local';
+    }
+    if (hostname.startsWith('fc') || hostname.startsWith('fd') || hostname.startsWith('fe80:'))
+        return 'private network';
+    return undefined;
+}
 function isSkillsInvocation(invoked, args) {
     const name = invoked.split('/').pop() || invoked;
     return name === 'skills' && args[0] === 'add' && args[1] === 'agent-permission';

package/dist/install.d.ts

@@ -4,8 +4,16 @@ export interface InstallResult {
     path: string;
     runnerPath: string;
     runnerCommand: string;
+    checkCommand: string;
+    apiKeyCommand: string;
+    doctorCommand: string;
+    repairCommand: string;
 }
 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, repairCommand?: string): string;
+export declare function buildInstructionBlock(adapter: Exclude<Adapter, 'auto'>, commands?: {
+    checkCommand?: string;
+    apiKeyCommand?: 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,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"}
+{"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;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,aAAa,EAAE,MAAM,CAAC;IACtB,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,CAiC9H;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,QAAQ,GAAE;IACR,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,UAqCP"}

package/dist/install.js

@@ -10,16 +10,32 @@ export async function installAgentInstructions(adapter, scope, runtime) {
     const runner = getRunnerPath(scope, runtime);
     const runnerCommand = getRunnerCommand(scope, runner);
     const repairCommand = getRepairCommand(resolved, scope);
+    const checkCommand = `${runnerCommand} check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code`;
+    const apiKeyCommand = `${runnerCommand} config set api-key <YOUR_API_KEY>`;
+    const doctorCommand = `${runnerCommand} config doctor`;
     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, repairCommand));
+    const next = upsertBlock(existing, buildInstructionBlock(resolved, {
+        checkCommand,
+        apiKeyCommand,
+        repairCommand,
+    }));
     await mkdir(dirname(path), { recursive: true });
     await writeLocalRunner(runner, runnerCommand);
     await writeFile(path, next);
-    return { adapter: resolved, path, runnerPath: runner, runnerCommand };
+    return {
+        adapter: resolved,
+        path,
+        runnerPath: runner,
+        runnerCommand,
+        checkCommand,
+        apiKeyCommand,
+        doctorCommand,
+        repairCommand,
+    };
 }
 export function upsertBlock(existing, blockBody) {
     const block = `${BLOCK_START}\n${blockBody.trim()}\n${BLOCK_END}`;
@@ -30,13 +46,16 @@ 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}`, repairCommand = `npx -y agent-permission@latest install --adapter ${adapter} --scope project`) {
+export function buildInstructionBlock(adapter, commands = {}) {
     const agentName = {
         codex: 'Codex',
         claude: 'Claude',
         chatgpt: 'ChatGPT',
         openclaw: 'OpenClaw',
     }[adapter];
+    const checkCommand = commands.checkCommand || `node ${PROJECT_RUNNER_PATH} check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code`;
+    const apiKeyCommand = commands.apiKeyCommand || `node ${PROJECT_RUNNER_PATH} config set api-key <YOUR_API_KEY>`;
+    const repairCommand = commands.repairCommand || `npx -y agent-permission@latest install --adapter ${adapter} --scope project`;
     return `# Agent Permission
 
 These instructions equip ${agentName} with Agent Permission preflight checks.
@@ -44,7 +63,7 @@ These instructions equip ${agentName} with Agent Permission preflight checks.
 Before crawling, summarizing, extracting, training on, transacting with, or posting to a URL, run:
 
 \`\`\`bash
-${runnerCommand} check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
+${checkCommand}
 \`\`\`
 
 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:
@@ -53,6 +72,12 @@ Do not use npm while handling an individual URL request. If the runner command i
 ${repairCommand}
 \`\`\`
 
+If the runner reports that the API key is missing, stop and ask the user to configure it with:
+
+\`\`\`bash
+${apiKeyCommand}
+\`\`\`
+
 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.
 
 Treat \`allow\` as permitted, \`deny\` as blocked, and \`escalate\` as requiring human approval before continuing. Preserve the returned receipt ID in task notes when a permission decision affects user-visible work.`;
@@ -168,6 +193,12 @@ async function runCheck(args) {
     throw new Error('Usage: agent-permission check <url> --action <crawl|summarize|extract|train|transact|post>');
   }
 
+  const localDecision = localUrlDecision(url, action);
+  if (localDecision) {
+    console.log(parsed.flags.json ? JSON.stringify(localDecision, null, 2) : formatCheckHuman(localDecision));
+    return parsed.flags['exit-code'] ? decisionExitCode(localDecision.decision) : 0;
+  }
+
   const config = await resolveConfig();
   const result = await checkPermission({
     url,
@@ -327,6 +358,73 @@ function decisionExitCode(decision) {
   return 1;
 }
 
+function localUrlDecision(url, action) {
+  const localKind = localUrlKind(url);
+  if (!localKind) return undefined;
+
+  const issuedAt = new Date().toISOString();
+  return {
+    id: 'local_url_check',
+    decision: 'allow',
+    confidence: 'high',
+    risk: 'low',
+    reasons: [
+      \`\${localKind} URL was not sent to the Agent Permission API; local development and in-app browser URLs are allowed without external preflight.\`,
+    ],
+    sources: [
+      {
+        type: 'local_url',
+        url,
+        fetched_at: issuedAt,
+        evidence: localKind,
+      },
+    ],
+    receipt: {
+      receipt_id: 'local_only_no_external_receipt',
+      check_id: 'local_url_check',
+      url_hash: 'local_only',
+      action,
+      decision: 'allow',
+      source_hashes: [],
+      issued_at: issuedAt,
+      account_id: 'local',
+      signature_alg: 'none',
+      signature: 'not_signed',
+    },
+  };
+}
+
+function localUrlKind(value) {
+  let parsed;
+  try {
+    parsed = new URL(value);
+  } catch {
+    return undefined;
+  }
+
+  if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') return undefined;
+
+  const hostname = parsed.hostname.toLowerCase().replace(/^\\[|\\]$/g, '');
+  if (hostname === 'localhost' || hostname.endsWith('.localhost')) return 'localhost';
+  if (hostname === '::1') return 'loopback';
+  if (hostname.startsWith('127.')) return 'loopback';
+  if (hostname === '0.0.0.0') return 'local bind address';
+  if (hostname.endsWith('.local')) return 'local network';
+
+  const parts = hostname.split('.').map((part) => Number(part));
+  if (parts.length === 4 && parts.every((part) => Number.isInteger(part) && part >= 0 && part <= 255)) {
+    const [first, second] = parts;
+    if (first === 10) return 'private network';
+    if (first === 172 && second >= 16 && second <= 31) return 'private network';
+    if (first === 192 && second === 168) return 'private network';
+    if (first === 169 && second === 254) return 'link-local';
+  }
+
+  if (hostname.startsWith('fc') || hostname.startsWith('fd') || hostname.startsWith('fe80:')) return 'private network';
+
+  return undefined;
+}
+
 function getConfigPath() {
   if (process.env.AGENT_PERMISSION_CONFIG) return process.env.AGENT_PERMISSION_CONFIG;
 

package/package.json

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