agent-permission 0.1.3 → 0.1.4

package/README.md

@@ -8,7 +8,7 @@ Give AI agents a permission gate before they touch external URLs.
 npx agent-permission 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.
+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.
 
 To install instructions and configure live checks in one step:
 
@@ -19,8 +19,8 @@ npx agent-permission install --adapter auto --api-key <YOUR_API_KEY>
 Add an API key when you want live checks from the command line, CI, or agent runs:
 
 ```bash
-npx agent-permission config set api-key <YOUR_API_KEY>
-npx -y agent-permission@latest check https://example.com/blog-post --action summarize --exit-code
+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
 ```
 
 ## What the Agent Runs
@@ -28,15 +28,13 @@ npx -y agent-permission@latest check https://example.com/blog-post --action summ
 After install, project instructions tell compatible agents to run:
 
 ```bash
-npx -y agent-permission@latest check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
+node .agent-permission/agent-permission.mjs check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
 ```
 
-The first run may need npm registry network access; later runs can use the local npm cache.
-
-If the binary is already available in the agent shell, the same check can also run as:
+If the local runner is missing, the installed instructions tell the agent to use npm as a fallback:
 
 ```bash
-agent-permission check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
+npx -y agent-permission@latest check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
 ```
 
 ## 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;AAgID,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;AAmID,wBAAgB,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,WAAW,CA2BtD"}

package/dist/cli.js

@@ -100,7 +100,10 @@ async function runInstall(args, runtime, io) {
     const adapter = parseAdapter(stringFlag(parsed, 'adapter') || parsed.positionals[0] || 'auto');
     const scope = parseScope(stringFlag(parsed, 'scope') || 'project');
     const result = await installAgentInstructions(adapter, scope, runtime);
-    const messages = [`Installed Agent Permission instructions for ${result.adapter} at ${result.path}`];
+    const messages = [
+        `Installed Agent Permission instructions for ${result.adapter} at ${result.path}`,
+        `Installed local Agent Permission runner at ${result.runnerPath}`,
+    ];
     const apiKey = stringFlag(parsed, 'api-key');
     if (apiKey) {
         const current = await readConfig(runtime);
@@ -110,7 +113,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 `npx agent-permission config set api-key <YOUR_API_KEY>` or set AGENT_PERMISSION_API_KEY.', 'Verify setup with `npx -y agent-permission@latest config doctor`.');
+            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\`.`);
         }
     }
     io.stdout(messages.join('\n'));

package/dist/install.d.ts

@@ -2,8 +2,10 @@ import { Adapter, InstallScope, Runtime } from './types.js';
 export interface InstallResult {
     adapter: Exclude<Adapter, 'auto'>;
     path: string;
+    runnerPath: string;
+    runnerCommand: 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'>): string;
+export declare function buildInstructionBlock(adapter: Exclude<Adapter, 'auto'>, runnerCommand?: 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,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAK5D,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;CACd;AAED,wBAAsB,wBAAwB,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,aAAa,CAAC,CAa9H;AAED,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,UAU9D;AAED,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,UA2BtE"}
+{"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"}

package/dist/install.js

@@ -1,19 +1,24 @@
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { dirname, join } from 'node:path';
+import { DEFAULT_API_URL } from './types.js';
 const BLOCK_START = '<!-- BEGIN:agent-permission -->';
 const BLOCK_END = '<!-- END:agent-permission -->';
+const PROJECT_RUNNER_PATH = '.agent-permission/agent-permission.mjs';
 export async function installAgentInstructions(adapter, scope, runtime) {
     const resolved = adapter === 'auto' ? await detectAdapter(runtime) : adapter;
     const path = getInstructionPath(resolved, scope, runtime);
+    const runner = getRunnerPath(scope, runtime);
+    const runnerCommand = getRunnerCommand(scope, runner);
     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));
+    const next = upsertBlock(existing, buildInstructionBlock(resolved, runnerCommand));
     await mkdir(dirname(path), { recursive: true });
+    await writeLocalRunner(runner);
     await writeFile(path, next);
-    return { adapter: resolved, path };
+    return { adapter: resolved, path, runnerPath: runner, runnerCommand };
 }
 export function upsertBlock(existing, blockBody) {
     const block = `${BLOCK_START}\n${blockBody.trim()}\n${BLOCK_END}`;
@@ -24,7 +29,7 @@ export function upsertBlock(existing, blockBody) {
     const prefix = existing.trimEnd();
     return prefix ? `${prefix}\n\n${block}\n` : `${block}\n`;
 }
-export function buildInstructionBlock(adapter) {
+export function buildInstructionBlock(adapter, runnerCommand = `node ${PROJECT_RUNNER_PATH}`) {
     const agentName = {
         codex: 'Codex',
         claude: 'Claude',
@@ -38,13 +43,13 @@ These instructions equip ${agentName} with Agent Permission preflight checks.
 Before crawling, summarizing, extracting, training on, transacting with, or posting to a URL, run:
 
 \`\`\`bash
-npx -y agent-permission@latest check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
+${runnerCommand} check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
 \`\`\`
 
-If the \`agent-permission\` binary is available in the agent shell, the same check can also run as:
+If the local runner is missing, run the same check through npm:
 
 \`\`\`bash
-agent-permission check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
+npx -y agent-permission@latest check <url> --action <crawl|summarize|extract|train|transact|post> --exit-code
 \`\`\`
 
 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.
@@ -78,6 +83,27 @@ function getInstructionPath(adapter, scope, runtime) {
         return join(runtime.cwd, 'AGENTS.md');
     return join(runtime.cwd, 'AGENTS.md');
 }
+function getRunnerPath(scope, runtime) {
+    if (scope === 'user') {
+        const home = runtime.homeDir || runtime.env.HOME || runtime.env.USERPROFILE || runtime.cwd;
+        const base = runtime.env.XDG_CONFIG_HOME || join(home, '.config');
+        return join(base, 'agent-permission', 'agent-permission.mjs');
+    }
+    return join(runtime.cwd, PROJECT_RUNNER_PATH);
+}
+function getRunnerCommand(scope, runnerPath) {
+    if (scope === 'user') {
+        return `node ${shellQuote(runnerPath)}`;
+    }
+    return `node ${PROJECT_RUNNER_PATH}`;
+}
+async function writeLocalRunner(path) {
+    await mkdir(dirname(path), { recursive: true });
+    await writeFile(path, buildLocalRunner(), { mode: 0o644 });
+}
+function shellQuote(value) {
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
 async function fileExists(path) {
     return (await readFileIfExists(path)) !== undefined;
 }
@@ -97,3 +123,258 @@ function isOpenClawInstructions(content) {
 function escapeRegExp(value) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
+function buildLocalRunner() {
+    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 ACTIONS = ['crawl', 'summarize', 'extract', 'train', 'transact', 'post'];
+
+const code = await main(process.argv.slice(2)).catch((err) => {
+  console.error(err instanceof Error ? err.message : 'Unexpected Agent Permission runner failure.');
+  return 1;
+});
+
+process.exitCode = code;
+
+async function main(args) {
+  const command = args[0];
+  const rest = args.slice(1);
+
+  if (!command || command === '--help' || command === '-h') {
+    console.log(helpText());
+    return 0;
+  }
+
+  if (command === 'check') return runCheck(rest);
+  if (command === 'config') return runConfig(rest);
+
+  console.error(\`Unknown command: \${command}\\n\\n\${helpText()}\`);
+  return 1;
+}
+
+async function runCheck(args) {
+  const parsed = parseFlags(args);
+  const url = parsed.positionals[0];
+  const action = parseAction(stringFlag(parsed, 'action') || parsed.positionals[1]);
+  if (!url || !action) {
+    throw new Error('Usage: agent-permission check <url> --action <crawl|summarize|extract|train|transact|post>');
+  }
+
+  const config = await resolveConfig();
+  const result = await checkPermission({
+    url,
+    action,
+    mode: parseMode(stringFlag(parsed, 'mode')) || config.defaultMode,
+    agent_user_agent: stringFlag(parsed, 'user-agent') || stringFlag(parsed, 'agent-user-agent'),
+    bypass_cache: Boolean(parsed.flags['bypass-cache']),
+  }, {
+    apiUrl: stringFlag(parsed, 'api-url') || config.apiUrl,
+    apiKey: stringFlag(parsed, 'api-key') || config.apiKey,
+  });
+
+  console.log(parsed.flags.json ? JSON.stringify(result, null, 2) : formatCheckHuman(result));
+  return parsed.flags['exit-code'] ? decisionExitCode(result.decision) : 0;
+}
+
+async function runConfig(args) {
+  const subcommand = args[0];
+  if (subcommand === 'set' && args[1] === 'api-key' && args[2]) {
+    const current = await readConfig();
+    const path = await writeConfig({ ...current, apiKey: args[2] });
+    console.log(\`Saved API key to \${path}\`);
+    return 0;
+  }
+
+  if (subcommand === 'set' && args[1] === 'api-url' && args[2]) {
+    const current = await readConfig();
+    const path = await writeConfig({ ...current, apiUrl: args[2] });
+    console.log(\`Saved API URL to \${path}\`);
+    return 0;
+  }
+
+  if (subcommand === 'doctor') {
+    const config = await resolveConfig();
+    console.log([
+      \`Config: \${getConfigPath()}\`,
+      \`API URL: \${config.apiUrl}\`,
+      \`API key: \${config.apiKey ? 'configured' : 'missing'}\`,
+      \`Default mode: \${config.defaultMode}\`,
+    ].join('\\n'));
+    return config.apiKey ? 0 : 1;
+  }
+
+  throw new Error('Usage: agent-permission config set api-key <key> | config set api-url <url> | config doctor');
+}
+
+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>\`.');
+  }
+
+  const res = await fetch(\`\${trimSlash(options.apiUrl)}/v1/check\`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      'Authorization': \`Bearer \${options.apiKey}\`,
+    },
+    body: JSON.stringify(params),
+  });
+
+  return readResponse(res);
+}
+
+async function readResponse(res) {
+  const body = await res.json().catch(() => ({}));
+  if (!res.ok) {
+    const message = typeof body?.message === 'string' ? body.message : \`API request failed with \${res.status}\`;
+    throw new Error(message);
+  }
+  return body;
+}
+
+function formatCheckHuman(result) {
+  const lines = [
+    \`Decision: \${result.decision}\`,
+    \`Confidence: \${result.confidence}\`,
+    \`Risk: \${result.risk}\`,
+    \`Check: \${result.id}\`,
+    '',
+    'Reasons:',
+    ...result.reasons.map((reason) => \`- \${reason}\`),
+  ];
+
+  if (result.sources?.length) {
+    lines.push('', 'Sources:', ...result.sources.map((source) => \`- \${source.type}: \${source.url}\`));
+  }
+
+  if (result.receipt?.receipt_id) {
+    lines.push('', \`Receipt: \${result.receipt.receipt_id}\`);
+  }
+
+  return lines.join('\\n');
+}
+
+function parseFlags(args) {
+  const flags = {};
+  const positionals = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+
+    const [rawKey, inlineValue] = arg.slice(2).split('=', 2);
+    if (inlineValue !== undefined) {
+      flags[rawKey] = inlineValue;
+      continue;
+    }
+
+    const next = args[i + 1];
+    if (next && !next.startsWith('--')) {
+      flags[rawKey] = next;
+      i += 1;
+    } else {
+      flags[rawKey] = true;
+    }
+  }
+
+  return { flags, positionals };
+}
+
+function stringFlag(parsed, name) {
+  const value = parsed.flags[name];
+  return typeof value === 'string' ? value : undefined;
+}
+
+function parseAction(value) {
+  return ACTIONS.includes(value) ? value : undefined;
+}
+
+function parseMode(value) {
+  if (!value) return undefined;
+  if (value === 'strict' || value === 'permissive') return value;
+  throw new Error('Mode must be strict or permissive.');
+}
+
+function decisionExitCode(decision) {
+  if (decision === 'allow') return 0;
+  if (decision === 'escalate') return 2;
+  if (decision === 'deny') return 3;
+  return 1;
+}
+
+function getConfigPath() {
+  if (process.env.AGENT_PERMISSION_CONFIG) return process.env.AGENT_PERMISSION_CONFIG;
+
+  const home = process.env.HOME || process.env.USERPROFILE || homedir() || '.';
+  if (process.env.XDG_CONFIG_HOME) {
+    return join(process.env.XDG_CONFIG_HOME, 'agent-permission', 'config.json');
+  }
+
+  if (process.platform === 'darwin') {
+    return join(home, 'Library', 'Application Support', 'agent-permission', 'config.json');
+  }
+
+  return join(home, '.config', 'agent-permission', 'config.json');
+}
+
+async function readConfig() {
+  try {
+    const raw = await readFile(getConfigPath(), 'utf8');
+    const parsed = JSON.parse(raw);
+    return {
+      apiKey: typeof parsed.apiKey === 'string' ? parsed.apiKey : undefined,
+      apiUrl: typeof parsed.apiUrl === 'string' ? parsed.apiUrl : undefined,
+      defaultMode: parsed.defaultMode === 'permissive' || parsed.defaultMode === 'strict' ? parsed.defaultMode : undefined,
+    };
+  } catch (err) {
+    if (err && typeof err === 'object' && err.code === 'ENOENT') return {};
+    throw err;
+  }
+}
+
+async function writeConfig(config) {
+  const path = getConfigPath();
+  await mkdir(dirname(path), { recursive: true });
+  await writeFile(path, \`\${JSON.stringify(config, null, 2)}\\n\`, { mode: 0o600 });
+  return path;
+}
+
+async function resolveConfig() {
+  const stored = await readConfig();
+  return {
+    apiKey: process.env.AGENT_PERMISSION_API_KEY || stored.apiKey || '',
+    apiUrl: process.env.AGENT_PERMISSION_API_URL || stored.apiUrl || DEFAULT_API_URL,
+    defaultMode: parseStoredMode(process.env.AGENT_PERMISSION_DEFAULT_MODE) || stored.defaultMode || 'strict',
+  };
+}
+
+function parseStoredMode(value) {
+  return value === 'strict' || value === 'permissive' ? value : undefined;
+}
+
+function trimSlash(value) {
+  return value.replace(/\\/+$/, '');
+}
+
+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
+
+Actions:
+  crawl, summarize, extract, train, transact, post
+
+Environment:
+  AGENT_PERMISSION_API_KEY, AGENT_PERMISSION_API_URL, AGENT_PERMISSION_DEFAULT_MODE\`;
+}
+`;
+}

package/package.json

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