@getbags/cash 0.3.1 → 0.4.0

package/README.md

@@ -117,3 +117,13 @@ Public `search` and `discover` work without credentials. Paid calls still requir
 `bags result <id> --field response.items --offset 0 --limit 20` and the `wallet_result` MCP tool read retained output without another provider call or payment. Results are private to the wallet and expire after 24 hours. Authentication fields are redacted; provider asset URLs may expire earlier. The fetch API and MCP accept `result_mode: "summary"`.
 
 MPP supports bounded one-shot `tempo:charge` with explicit chain/currency checks. Hosted session opening is disabled until durable close can be confirmed. `bags sessions list` shows existing session reservations. Hosted `sessions close` currently reports unsupported cleanup and keeps the hold; it does not report the channel closed. Existing channels and reservations remain owned when cleanup fails.
+
+### Task fit, accepted jobs and asset copies (0.4.0)
+
+`bags search "email from LinkedIn" --requirements '{"inputs":{"depth":"full"},"outputs":["email"],"unit":"contact"}' --format json` returns advertised capability fit, health and conservative cost comparisons. Unknown controls, contracts, units or funding remain unknown. Prices are indicative: check the exact method/body before paying.
+
+`bags result <id> --refresh` explicitly makes one unpaid GET to an advertised async status URL. It never repeats the initial request, pays a status challenge or forwards your wallet credentials. Providers without a safe polling contract remain explicit; terminal costs are separately labelled when provider-reported.
+
+`bags result <id> --retain-asset '<exact-advertised-url>'` explicitly requests a private copy. At most two assets per result, 2 MiB each; copies expire with the retained result. The response includes measured size/SHA256 and an authenticated download URL. Use this option separately from field/page/refresh flags. Plain `bags result <id>` remains a stored read.
+
+Registration returns `reusable_skill.markdown`, a small origin/task pointer that refreshes discovery and contracts on each use. It includes no credential or spending authority.

package/dist/api.d.ts

@@ -28,6 +28,10 @@ export type DiscoverEndpoint = {
     source?: 'bags' | 'bazaar' | 'registered';
     input_schema?: unknown;
     output_schema?: unknown;
+    pricing?: {
+        kind?: string;
+        indicative?: boolean;
+    };
     score?: number;
     signals?: {
         text_match: number;
@@ -123,7 +127,7 @@ export declare function redeem(opts: {
 }): Promise<RedeemResponse>;
 export declare function getBalance(token: string): Promise<BalanceResponse>;
 export declare function discover(token: string, query?: string): Promise<DiscoverResponse>;
-export declare function search(token: string, query: string): Promise<DiscoverResponse>;
+export declare function search(token: string, query: string, requirements?: Record<string, unknown>): Promise<DiscoverResponse>;
 export declare function checkEndpoint(token: string, input: {
     url: string;
     method?: string;
@@ -188,4 +192,6 @@ export declare function getResult(token: string, input: {
     field?: string;
     offset?: number;
     limit?: number;
+    refresh?: boolean;
+    retain_asset_url?: string;
 }): Promise<Record<string, unknown>>;

package/dist/api.js

@@ -98,8 +98,8 @@ export async function discover(token, query) {
         query: data.query,
     };
 }
-export async function search(token, query) {
-    const path = `/api/wallet/search?q=${encodeURIComponent(query)}`;
+export async function search(token, query, requirements) {
+    const path = `/api/wallet/search?q=${encodeURIComponent(query)}${requirements ? '&requirements=' + encodeURIComponent(JSON.stringify(requirements)) : ''}`;
     const body = await apiRequest(path, { token });
     const data = unwrapPayload(body);
     return {
@@ -245,7 +245,18 @@ export async function registerOrigin(token, origin, opts = {}) {
 }
 /** Read an owned result; never starts another provider call or payment. */
 export async function getResult(token, input) {
+    if (input.retain_asset_url) {
+        if (input.refresh || input.field || input.offset !== undefined || input.limit !== undefined)
+            throw new Error('Asset retention cannot be combined with read/refresh options');
+        return unwrapPayload(await apiRequest('/api/wallet/results', {
+            method: 'POST',
+            token,
+            body: { id: input.id, retain_asset_url: input.retain_asset_url },
+        }));
+    }
     const query = new URLSearchParams({ id: input.id });
+    if (input.refresh)
+        query.set('refresh', 'true');
     if (input.field)
         query.set('field', input.field);
     if (input.offset !== undefined)

package/dist/index.js

@@ -22,9 +22,12 @@ function printDiscoverTable(endpoints) {
     const rows = endpoints.map((ep) => ({
         url: ep.url,
         method: ep.method,
-        price: typeof ep.price_usd === 'number'
-            ? `$${ep.price_usd.toFixed(6).replace(/(\.\d{2,}?)0+$/, '$1')}`
-            : String(ep.price_usd),
+        price: ep.pricing?.kind === 'unknown' ||
+            (ep.source === 'registered' && Number(ep.price_usd) === 0 && ep.pricing?.kind !== 'free')
+            ? 'unknown (check)'
+            : typeof ep.price_usd === 'number'
+                ? `$${ep.price_usd.toFixed(6).replace(/(\.\d{2,}?)0+$/, '$1')}`
+                : String(ep.price_usd),
         merchant: ep.merchant_name ?? '',
         source: ep.source ?? 'bags',
     }));
@@ -90,7 +93,7 @@ async function main() {
                 return;
             }
             case 'search': {
-                const result = await search(loadCredentials()?.token ?? '', parsed.query);
+                const result = await search(loadCredentials()?.token ?? '', parsed.query, parsed.requirements);
                 if (parsed.format === 'json') {
                     printJson(result);
                 }

package/dist/mcp-server.d.ts

@@ -7,10 +7,12 @@ export type WalletMcpApi = {
         field?: string;
         offset?: number;
         limit?: number;
+        refresh?: boolean;
+        retain_asset_url?: string;
     }) => Promise<Record<string, unknown>>;
     getBalance: (token: string) => Promise<BalanceResponse>;
     discover: (token: string, query?: string) => Promise<DiscoverResponse>;
-    search: (token: string, query: string) => Promise<DiscoverResponse>;
+    search: (token: string, query: string, requirements?: Record<string, unknown>) => Promise<DiscoverResponse>;
     checkEndpoint: (token: string, input: {
         url: string;
         method?: string;

package/dist/mcp-server.js

@@ -117,9 +117,20 @@ export function createWalletMcpServer(deps = {}) {
         description: 'Natural-language search for x402 endpoints. BAGS catalog first, best-effort ecosystem (Bazaar) second. Returns price, description, schemas when available.',
         inputSchema: {
             query: z.string().min(1).describe('Natural-language or keyword query'),
+            requirements: z
+                .object({
+                inputs: z
+                    .record(z.string().min(1).max(100), z.union([z.string().max(256), z.number(), z.boolean(), z.null()]))
+                    .refine((v) => Object.keys(v).length <= 32, 'At most 32 input controls')
+                    .optional(),
+                outputs: z.array(z.string().min(1).max(100)).max(16).optional(),
+                unit: z.string().min(1).max(50).optional(),
+            })
+                .strict()
+                .optional(),
         },
         annotations: { readOnlyHint: true, openWorldHint: true },
-    }, async (args) => textContent(await api.search(resolveToken(deps) ?? '', String(args.query ?? '').trim())));
+    }, async (args) => textContent(await api.search(resolveToken(deps) ?? '', String(args.query ?? '').trim(), args.requirements)));
     server.registerTool('wallet_check_endpoint', {
         title: 'Check endpoint quote',
         description: 'Probe an x402 URL for schema + exact price quote without paying (AgentCash check parity). Use before wallet_fetch.',
@@ -139,11 +150,21 @@ export function createWalletMcpServer(deps = {}) {
         description: 'Retrieve full output, fields or array pages from a previous wallet_fetch result for 24 hours. Does not execute or charge again. Provider asset URLs may expire earlier.',
         inputSchema: {
             id: z.string().uuid(),
+            refresh: z
+                .boolean()
+                .optional()
+                .describe('Make one unpaid GET to the advertised async status URL; never authorizes payment'),
+            retain_asset_url: z
+                .string()
+                .url()
+                .max(8192)
+                .optional()
+                .describe('Explicitly copy an advertised asset privately, at most two 2 MiB assets for the result lifetime'),
             field: z.string().max(200).optional(),
             offset: z.number().int().nonnegative().optional(),
             limit: z.number().int().min(1).max(100).optional(),
         },
-        annotations: { readOnlyHint: true, openWorldHint: false },
+        annotations: { readOnlyHint: false, openWorldHint: true },
     }, async (args) => withToken(async (token) => textContent(await api.getResult(token, args))));
     server.registerTool('wallet_fetch', {
         title: 'Wallet fetch (pay + proxy)',

package/dist/parse.d.ts

@@ -17,6 +17,8 @@ export type ParsedArgs = {
     field?: string;
     offset?: number;
     limit?: number;
+    refresh?: boolean;
+    retain_asset_url?: string;
 } | {
     command: 'discover';
     format: 'json' | 'pretty';
@@ -78,6 +80,7 @@ export type ParsedArgs = {
 } | {
     command: 'search';
     query: string;
+    requirements?: Record<string, unknown>;
     format: 'json' | 'pretty';
 } | {
     command: 'register';

package/dist/parse.js

@@ -7,7 +7,7 @@ const VALID_CLIENTS = ['cursor', 'claude', 'codex'];
 const COMMAND_USAGE = {
     redeem: 'usage: bags redeem <code> | bags redeem --test',
     balance: 'usage: bags balance',
-    result: 'usage: bags result <id> [--field path] [--offset N] [--limit N]',
+    result: 'usage: bags result <id> [--field path] [--offset N] [--limit N] [--refresh] [--retain-asset URL]',
     discover: 'usage: bags discover [query] [--format json|pretty]',
     search: 'usage: bags search <query> [--format json|pretty]',
     check: 'usage: bags check <url> [flags]',
@@ -449,9 +449,18 @@ export function parseArgs(argv) {
                 id,
             };
             for (let i = 1; i < rest.length; i += 2) {
+                if (rest[i] === '--refresh') {
+                    out.refresh = true;
+                    i--;
+                    continue;
+                }
                 const flag = rest[i], value = rest[i + 1];
-                if (!value || !['--field', '--offset', '--limit'].includes(flag))
+                if (!value || !['--field', '--offset', '--limit', '--retain-asset'].includes(flag))
                     return { command: 'error', message: COMMAND_USAGE.result };
+                if (flag === '--retain-asset') {
+                    out.retain_asset_url = value;
+                    continue;
+                }
                 if (flag === '--field')
                     out.field = value;
                 else {
@@ -466,6 +475,9 @@ export function parseArgs(argv) {
                         out.limit = n;
                 }
             }
+            if (out.retain_asset_url &&
+                (out.refresh || out.field || out.offset !== undefined || out.limit !== undefined))
+                return { command: 'error', message: '--retain-asset cannot be combined with read/refresh flags' };
             return out;
         }
         case 'transactions': {
@@ -647,7 +659,24 @@ export function parseArgs(argv) {
             if ('error' in parsed)
                 return { command: 'error', message: parsed.error };
             const queryWords = [];
-            for (const arg of parsed.rest) {
+            let requirements;
+            for (let i = 0; i < parsed.rest.length; i++) {
+                const arg = parsed.rest[i];
+                if (arg === '--requirements') {
+                    const value = parsed.rest[++i];
+                    try {
+                        if (!value || value.length > 4096)
+                            throw new Error();
+                        const obj = JSON.parse(value);
+                        if (!obj || typeof obj !== 'object' || Array.isArray(obj))
+                            throw new Error();
+                        requirements = obj;
+                    }
+                    catch {
+                        return { command: 'error', message: '--requirements must be a bounded JSON object' };
+                    }
+                    continue;
+                }
                 if (arg.startsWith('-'))
                     return { command: 'error', message: `unknown flag: ${arg}` };
                 queryWords.push(arg);
@@ -655,7 +684,7 @@ export function parseArgs(argv) {
             const query = queryWords.join(' ').trim();
             if (!query)
                 return { command: 'error', message: 'usage: bags search <query>' };
-            return { command: 'search', query, format: parsed.format };
+            return { command: 'search', query, format: parsed.format, ...(requirements ? { requirements } : {}) };
         }
         case 'register': {
             const origin = rest[0];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@getbags/cash",
-  "version": "0.3.1",
+  "version": "0.4.0",
   "description": "BAGS Cash CLI \u2014 hosted agent wallet for x402 (balance \u2192 discover \u2192 check \u2192 fetch)",
   "type": "module",
   "bin": {