@techdigger/humanode-agentlink-cli 0.3.3 → 0.3.5

package/README.md

@@ -30,6 +30,8 @@ After the owner completes linking in the browser, check the result:
 agentlink status
 ```
 
+For the first protected-route test, start with a `free-trial` route before moving to stricter gating or more complex payment flows.
+
 ## Commands
 
 ### `agentlink init`

package/REGISTRATION.md

@@ -1,10 +1,10 @@
 # Humanode Agentlink — Agent Developer Guide
 
-Link your AI agent to a biomapped human and unlock free or discounted access to x402 APIs.
+Link your AI agent to a biomapped human and unlock verified-human access on x402 APIs.
 
 ## What linking does
 
-When your agent is linked to a biomapped owner, platforms using Humanode Agentlink can identify your agent as acting on behalf of a real human. This unlocks better pricing: free tiers, free trials, or discounts that are unavailable to unlinked agents.
+When your agent is linked to a biomapped owner, platforms using Humanode Agentlink can identify your agent as acting on behalf of a real human. This unlocks better route behavior: free tiers, free trials, or linked-only gating that are unavailable to unlinked agents.
 
 ## Prerequisites
 
@@ -112,6 +112,8 @@ Possible results:
 
 Use `--json` for machine-readable output.
 
+For the first protected-route test, start with a `free-trial` route. It is the fastest way to prove the linked-human path end to end.
+
 ## Manual consent flow
 
 If you do not want the CLI to create a link session URL, use the lower-level `authorize-link` command:

package/dist/commands/authorize-link.js

@@ -1,6 +1,6 @@
 import { isAddress } from 'viem';
 import { createAgentLinkConsent } from '@techdigger/humanode-agentlink';
-import { CliError, assertNoExtraPositionals, createConsolePrompter, defaultDeadline, parseFlags, parseFutureDeadline, parseRequiredAddress, resolveNetwork, resolvePrivateKey, resolveRegistryAddress, resolveRpcUrl, } from '../lib/core.js';
+import { CliError, assertNoExtraPositionals, createConsolePrompter, defaultDeadline, parseFlags, parseFutureDeadline, resolveNetwork, resolvePrivateKey, resolveRegistryAddress, resolveRpcUrl, } from '../lib/core.js';
 export async function parseAuthorizeLinkOptions(argv, env, now, overrides = {}) {
     const parsed = parseFlags(argv);
     assertNoExtraPositionals('authorize-link', parsed.positionals);

package/dist/commands/request.d.ts

@@ -0,0 +1,23 @@
+import type { Hex } from 'viem';
+import { type EnvSource, type NetworkName } from '../lib/core.js';
+export interface RequestOptions {
+    url: string;
+    method: string;
+    network: NetworkName;
+    count: number;
+    json: boolean;
+    privateKey: Hex;
+}
+export interface RequestResult {
+    request: number;
+    status: number;
+    body: string;
+}
+export interface RequestDeps {
+    fetchImpl: typeof fetch;
+}
+export declare function parseRequestOptions(argv: string[], env: EnvSource, overrides?: {
+    privateKey?: string;
+}): RequestOptions;
+export declare function runRequest(options: RequestOptions, deps?: Partial<RequestDeps>): Promise<RequestResult[]>;
+export declare function formatRequestOutput(results: RequestResult[], json: boolean): string;

package/dist/commands/request.js

@@ -0,0 +1,59 @@
+import { buildAgentLinkHeader } from '@techdigger/humanode-agentlink';
+import { CliError, assertNoExtraPositionals, parseFlags, resolveNetwork, resolvePrivateKey, } from '../lib/core.js';
+export function parseRequestOptions(argv, env, overrides = {}) {
+    const parsed = parseFlags(argv);
+    if (parsed.positionals.length === 0) {
+        throw new CliError('Missing URL. Usage: agentlink request <url> [options]');
+    }
+    assertNoExtraPositionals('request', parsed.positionals.slice(1));
+    const url = parsed.positionals[0];
+    try {
+        new URL(url);
+    }
+    catch {
+        throw new CliError(`Invalid URL: "${url}"`);
+    }
+    const countRaw = parsed.values.count;
+    const count = countRaw ? parseInt(countRaw, 10) : 1;
+    if (isNaN(count) || count < 1) {
+        throw new CliError(`--count must be a positive integer, got "${countRaw}"`);
+    }
+    const network = resolveNetwork(parsed.values.network, env);
+    return {
+        url,
+        method: (parsed.values.method ?? 'GET').toUpperCase(),
+        network,
+        count,
+        json: parsed.flags.has('json'),
+        privateKey: resolvePrivateKey(parsed.values['private-key'], env, overrides.privateKey),
+    };
+}
+export async function runRequest(options, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const results = [];
+    for (let i = 1; i <= options.count; i++) {
+        const agentlinkHeader = await buildAgentLinkHeader(options.url, {
+            privateKey: options.privateKey,
+            network: options.network,
+        });
+        let response;
+        try {
+            response = await fetchImpl(new Request(options.url, {
+                method: options.method,
+                headers: { agentlink: agentlinkHeader },
+            }));
+        }
+        catch (error) {
+            throw new CliError(`Request ${i} failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+        const body = await response.text();
+        results.push({ request: i, status: response.status, body });
+    }
+    return results;
+}
+export function formatRequestOutput(results, json) {
+    if (json) {
+        return JSON.stringify(results, null, 2);
+    }
+    return results.map(r => `Request ${r.request}  ${r.status}  ${r.body.slice(0, 200)}`).join('\n');
+}

package/dist/help.d.ts

@@ -3,4 +3,5 @@ export declare function getKeystoreHelpText(): string;
 export declare function getAuthorizeLinkHelpText(): string;
 export declare function getStatusHelpText(): string;
 export declare function getLinkHelpText(): string;
+export declare function getRequestHelpText(): string;
 export declare function getInitHelpText(): string;

package/dist/help.js

@@ -7,6 +7,7 @@ Commands:
   link             Generate consent and open a linker URL for owner approval
   authorize-link   Generate a one-time EIP-712 consent blob for manual linking
   status           Check whether an agent is linked and active
+  request          Send a signed agentlink request to a protected endpoint
 
 Flags:
   --help, -h       Show this help text
@@ -108,6 +109,32 @@ Options:
   --help         Show this help message
 `;
 }
+export function getRequestHelpText() {
+    return `Usage:
+  agentlink request <url> [options]
+
+Description:
+  Send a signed agentlink request to a URL. Builds a SIWE payload signed with
+  your agent wallet, attaches it as the "agentlink" header, and prints the
+  response. Use --count to repeat the request (e.g. to test free-trial limits).
+
+Options:
+  --method       HTTP method (default: GET)
+  --count        Number of times to send the request (default: 1)
+  --network      base | base-sepolia (default: BIOMAPPER_NETWORK or base-sepolia)
+  --private-key-stdin  Read the agent private key from stdin
+  --private-key  Dev-only: pass key directly as 0x-prefixed hex
+  --json         Output results as JSON
+  --help         Show this help message
+
+Key resolution order: keystore (default) → --private-key-stdin → --private-key → AGENT_PRIVATE_KEY env
+
+Examples:
+  agentlink request http://localhost:3000/data
+  agentlink request http://75.119.141.48:3000/data --count 4
+  agentlink request https://api.example.com/resource --method POST --network base
+`;
+}
 export function getInitHelpText() {
     return `Usage:
   agentlink init [dir] [options]

package/dist/index.d.ts

@@ -13,5 +13,6 @@ export interface CliRuntime {
     openUrl: (url: string) => Promise<void>;
     readStdin: () => Promise<string>;
     readPassword: (prompt: string) => Promise<string>;
+    fetchImpl: typeof fetch;
 }
 export declare function runCli(argv?: string[], overrides?: Partial<CliRuntime>): Promise<number>;

package/dist/index.js

@@ -6,10 +6,11 @@ import { formatInitOutput, parseInitOptions, runInit } from './commands/init.js'
 import { formatLinkOutput, parseLinkOptions, runLink } from './commands/link.js';
 import { formatStatusOutput, parseStatusOptions, runStatus } from './commands/status.js';
 import { parseAuthorizeLinkOptions, runAuthorizeLink } from './commands/authorize-link.js';
+import { formatRequestOutput, parseRequestOptions, runRequest } from './commands/request.js';
 import { runKeystoreAddress, runKeystoreDelete, runKeystoreSet } from './commands/keystore.js';
 import { CliError, formatJson, loadEnvFiles, openUrlInBrowser, parseFlags, readAllFromStdin, readPassword } from './lib/core.js';
 import { decryptKeystore, keystoreExists, keystorePath } from './lib/keystore.js';
-import { getAuthorizeLinkHelpText, getInitHelpText, getKeystoreHelpText, getLinkHelpText, getRootHelpText, getStatusHelpText, } from './help.js';
+import { getAuthorizeLinkHelpText, getInitHelpText, getKeystoreHelpText, getLinkHelpText, getRequestHelpText, getRootHelpText, getStatusHelpText, } from './help.js';
 import { VERSION } from './version.js';
 import { buildEmbeddedHostedLinkUrl, createAgentLinkConsent, createBiomapperQueryClient, createLinkSession, } from '@techdigger/humanode-agentlink';
 function writeLine(write, text) {
@@ -34,6 +35,7 @@ export async function runCli(argv = process.argv.slice(2), overrides = {}) {
         openUrl: overrides.openUrl ?? openUrlInBrowser,
         readStdin: overrides.readStdin ?? readAllFromStdin,
         readPassword: overrides.readPassword ?? readPassword,
+        fetchImpl: overrides.fetchImpl ?? fetch,
     };
     const [command, ...args] = argv;
     try {
@@ -183,6 +185,17 @@ export async function runCli(argv = process.argv.slice(2), overrides = {}) {
                 }, runtime.env);
                 return 0;
             }
+            case 'request': {
+                if (args.includes('--help') || args.includes('-h')) {
+                    writeLine(runtime.stdout, getRequestHelpText());
+                    return 0;
+                }
+                const requestPrivateKey = await readPrivateKeyFromStdin(args, runtime);
+                const requestOptions = parseRequestOptions(args, runtime.env, { privateKey: requestPrivateKey });
+                const requestResults = await runRequest(requestOptions, { fetchImpl: runtime.fetchImpl });
+                writeLine(runtime.stdout, formatRequestOutput(requestResults, requestOptions.json));
+                return 0;
+            }
             default:
                 throw new CliError(`Unknown command "${command}". Run "agentlink --help" for available commands.`);
         }

package/dist/lib/core.d.ts

@@ -4,11 +4,13 @@ export declare const NETWORKS: {
         readonly label: "Base mainnet";
         readonly biomapperAppUrl: string;
         readonly defaultRegistry: Address;
+        readonly chainId: 8453;
     };
     readonly 'base-sepolia': {
         readonly label: "Base Sepolia";
         readonly biomapperAppUrl: string;
         readonly defaultRegistry: Address;
+        readonly chainId: 84532;
     };
 };
 export type NetworkName = keyof typeof NETWORKS;

package/dist/lib/core.js

@@ -12,11 +12,13 @@ export const NETWORKS = {
         label: 'Base mainnet',
         biomapperAppUrl: BIOMAPPER_APP_URLS.base,
         defaultRegistry: '0x', // populated at mainnet launch
+        chainId: 8453,
     },
     'base-sepolia': {
         label: 'Base Sepolia',
         biomapperAppUrl: BIOMAPPER_APP_URLS['base-sepolia'],
         defaultRegistry: '0xc0fb26BaACe7E1BCb3aFFD547AD5f2cAc4A4F51b',
+        chainId: 84532,
     },
 };
 export const TEMPLATE_NAMES = ['langchain', 'vercel-ai-sdk', 'mcp'];
@@ -239,17 +241,16 @@ export function getPackageManagerInstallCommand(packageManager) {
 export function getPackageManagerRunCommand(packageManager, script) {
     return `${PM_COMMANDS[packageManager].run} ${script}`;
 }
-const HUMANODE_PACKAGE_VERSION = '^0.2.0';
 const HUMANODE_PACKAGE_META = {
-    agentlink: { dirName: 'agentlink', packageName: '@techdigger/humanode-agentlink', version: HUMANODE_PACKAGE_VERSION },
+    agentlink: { dirName: 'agentlink', packageName: '@techdigger/humanode-agentlink', version: '^0.3.0' },
     langchain: {
         dirName: 'langchain',
         packageName: '@techdigger/humanode-agentlink-langchain',
-        version: HUMANODE_PACKAGE_VERSION,
+        version: '^0.1.0',
     },
-    aiSdk: { dirName: 'ai-sdk', packageName: '@techdigger/humanode-agentlink-ai-sdk', version: HUMANODE_PACKAGE_VERSION },
-    mcp: { dirName: 'mcp', packageName: '@techdigger/humanode-agentlink-mcp', version: HUMANODE_PACKAGE_VERSION },
-    cli: { dirName: 'cli', packageName: '@techdigger/humanode-agentlink-cli', version: HUMANODE_PACKAGE_VERSION },
+    aiSdk: { dirName: 'ai-sdk', packageName: '@techdigger/humanode-agentlink-ai-sdk', version: '^0.1.0' },
+    mcp: { dirName: 'mcp', packageName: '@techdigger/humanode-agentlink-mcp', version: '^0.1.0' },
+    cli: { dirName: 'cli', packageName: '@techdigger/humanode-agentlink-cli', version: '^0.3.5' },
 };
 async function pathExists(targetPath) {
     try {

package/dist/templates.js

@@ -7,7 +7,7 @@ const MCP_SDK_VERSION = '^1.12.1';
 const DOTENV_VERSION = '^17.3.1';
 const TSX_VERSION = '^4.19.4';
 const TYPESCRIPT_VERSION = '^5.8.3';
-function buildCommonEnv(input, _includeOpenAI) {
+function buildCommonEnv(input) {
     const lines = [
         `BIOMAPPER_NETWORK=${input.network}`,
         `BIOMAPPER_REGISTRY=${input.registry}`,
@@ -210,6 +210,10 @@ ${getPackageManagerRunCommand(input.packageManager, 'link')} -- --owner 0xOwner
 \`\`\`bash
 ${getPackageManagerRunCommand(input.packageManager, 'status')}
 \`\`\`
+
+## Recommended First Route Test
+
+After linking succeeds, start by pointing the agent at a \`free-trial\` route. That proves the linked-human path before you move to stricter gating or more advanced payment flows.
 `;
 }
 function buildLangChainReadme(input) {
@@ -253,21 +257,21 @@ export function buildTemplateFiles(input) {
         case 'langchain':
             return [
                 ...commonFiles,
-                { path: '.env.local', content: buildCommonEnv(input, true) },
+                { path: '.env.local', content: buildCommonEnv(input) },
                 { path: 'README.md', content: buildLangChainReadme(input) },
                 { path: 'src/index.ts', content: buildLangChainSource() },
             ];
         case 'vercel-ai-sdk':
             return [
                 ...commonFiles,
-                { path: '.env.local', content: buildCommonEnv(input, true) },
+                { path: '.env.local', content: buildCommonEnv(input) },
                 { path: 'README.md', content: buildAISDKReadme(input) },
                 { path: 'src/index.ts', content: buildAISource() },
             ];
         case 'mcp':
             return [
                 ...commonFiles,
-                { path: '.env.local', content: buildCommonEnv(input, false) },
+                { path: '.env.local', content: buildCommonEnv(input) },
                 { path: 'README.md', content: buildMcpReadme(input) },
                 { path: 'mcp.config.json', content: buildMcpConfig(input.packageManager) },
                 { path: 'src/index.ts', content: buildMcpSource() },

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@techdigger/humanode-agentlink-cli",
-	"version": "0.3.3",
+	"version": "0.3.5",
 	"description": "Scaffold, link, and inspect Biomapper-ready agent projects.",
 	"type": "module",
 	"main": "dist/index.js",
@@ -23,8 +23,9 @@
 		"cli": "tsx src/index.ts"
 	},
 	"dependencies": {
-		"@techdigger/humanode-agentlink": "^0.2.0",
+		"@techdigger/humanode-agentlink": "^0.3.0",
 		"posthog-node": "^5.21.2",
+		"siwe": "^2.3.2",
 		"viem": "^2.46.2"
 	},
 	"keywords": [
@@ -35,7 +36,7 @@
 		"mcp"
 	],
 	"devDependencies": {
-		"@types/node": "^24.3.2",
+		"@types/node": "^24.12.2",
 		"tsx": "^4.19.4",
 		"typescript": "^5.9.3"
 	}