@elisym/mcp 0.8.10 → 0.8.11

package/dist/index.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { LIMITS, DEFAULT_KIND_OFFSET, SolanaPaymentStrategy, makeCensor, DEFAULT_REDACT_PATHS, validateAgentName, RELAYS, toDTag, formatAssetAmount, USDC_SOLANA_DEVNET, estimateSolFeeLamports, formatFeeBreakdown, resolveAssetFromPaymentRequest as resolveAssetFromPaymentRequest$1, parseAssetAmount, ElisymIdentity, ElisymClient, NATIVE_SOL, resolveKnownAsset, getProtocolProgramId, getProtocolConfig, assetKey, assetByKey, KNOWN_ASSETS } from '@elisym/sdk';
-import { listAgents, createAgentDir, writeYaml, writeSecrets, loadAgent, globalConfigPath } from '@elisym/sdk/agent-store';
+import { LIMITS, DEFAULT_KIND_OFFSET, SolanaPaymentStrategy, makeCensor, DEFAULT_REDACT_PATHS, validateAgentName, RELAYS, toDTag, formatAssetAmount, USDC_SOLANA_DEVNET, estimateSolFeeLamports, formatFeeBreakdown, resolveAssetFromPaymentRequest as resolveAssetFromPaymentRequest$1, parseAssetAmount, ElisymIdentity, ElisymClient, NATIVE_SOL, resolveKnownAsset, estimateNetworkBaseline, formatNetworkBaseline, getProtocolProgramId, getProtocolConfig, assetKey, assetByKey, KNOWN_ASSETS } from '@elisym/sdk';
+import { listAgents, createAgentDir, writeYaml, writeSecrets, resolveAgent, loadAgent, globalConfigPath, writeFileAtomic as writeFileAtomic$1 } from '@elisym/sdk/agent-store';
 import { loadGlobalConfig, writeGlobalConfig } from '@elisym/sdk/node';
 import { getBase58Encoder, getBase58Decoder, generateKeyPairSigner, address, createSolanaRpcSubscriptions, sendAndConfirmTransactionFactory, getSignatureFromTransaction, pipe, createTransactionMessage, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions, signTransactionMessageWithSigners, createKeyPairSignerFromBytes, createSolanaRpc, isAddress } from '@solana/kit';
 import { Command } from 'commander';
@@ -352,6 +352,13 @@ function payment() {
   _paymentStrategy ??= new SolanaPaymentStrategy();
   return _paymentStrategy;
 }
+function decodeNpub(npub) {
+  const decoded = nip19.decode(npub);
+  if (decoded.type !== "npub") {
+    throw new Error(`Expected npub, got ${decoded.type}`);
+  }
+  return decoded.data;
+}
 
 // src/install.ts
 function elisymPackageArgs() {
@@ -752,13 +759,15 @@ async function buildAgentInstance(name, config) {
       );
     }
   }
+  const resolved = resolveAgent(name, process.cwd());
   return {
     client,
     identity,
     name,
     network: config.network,
     solanaKeypair,
-    security: config.security ?? {}
+    security: config.security ?? {},
+    agentDir: resolved?.dir
   };
 }
 var agentTools = [
@@ -1156,6 +1165,107 @@ function sanitizeField(input, maxLen) {
   }
   return text;
 }
+var CUSTOMER_HISTORY_FILENAME = ".customer-history.json";
+var MAX_HISTORY_ENTRIES = 500;
+var StatusSchema = z.enum(["completed", "failed", "timeout"]);
+var FeedbackSchema = z.enum(["positive", "negative"]);
+var CustomerJobEntrySchema = z.object({
+  jobEventId: z.string().min(1).max(128),
+  capability: z.string().min(1).max(200),
+  providerPubkey: z.string().regex(/^[a-f0-9]{64}$/),
+  providerName: z.string().max(200).optional(),
+  paidAmountSubunits: z.string().max(40).optional(),
+  assetKey: z.string().max(80).optional(),
+  status: StatusSchema,
+  submittedAt: z.number().int().nonnegative(),
+  completedAt: z.number().int().nonnegative(),
+  resultPreview: z.string().max(500).optional(),
+  paymentSig: z.string().max(128).optional(),
+  customerFeedback: FeedbackSchema.optional()
+}).strict();
+var CustomerHistorySchema = z.object({
+  version: z.literal(1),
+  jobs: z.array(CustomerJobEntrySchema)
+}).strict();
+var EMPTY = { version: 1, jobs: [] };
+var writeLocks = /* @__PURE__ */ new Map();
+function withLock(path, fn) {
+  const previous = writeLocks.get(path) ?? Promise.resolve();
+  const next = previous.then(fn, fn);
+  writeLocks.set(
+    path,
+    next.finally(() => {
+      if (writeLocks.get(path) === next) {
+        writeLocks.delete(path);
+      }
+    })
+  );
+  return next;
+}
+function pathFor(agentDir) {
+  return join(agentDir, CUSTOMER_HISTORY_FILENAME);
+}
+async function readRaw(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch {
+    return { ...EMPTY, jobs: [] };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const result = CustomerHistorySchema.safeParse(parsed);
+    return result.success ? result.data : { ...EMPTY, jobs: [] };
+  } catch {
+    return { ...EMPTY, jobs: [] };
+  }
+}
+async function writeRaw(path, history) {
+  const body = JSON.stringify(history, null, 2) + "\n";
+  await writeFileAtomic$1(path, body, 384);
+}
+async function readCustomerHistory(agentDir) {
+  return readRaw(pathFor(agentDir));
+}
+async function appendCustomerJob(agentDir, entry) {
+  const validated = CustomerJobEntrySchema.parse(entry);
+  const path = pathFor(agentDir);
+  return withLock(path, async () => {
+    const history = await readRaw(path);
+    const existingIndex = history.jobs.findIndex((job) => job.jobEventId === validated.jobEventId);
+    if (existingIndex >= 0) {
+      history.jobs[existingIndex] = validated;
+    } else {
+      history.jobs.push(validated);
+    }
+    if (history.jobs.length > MAX_HISTORY_ENTRIES) {
+      history.jobs.sort((left, right) => left.submittedAt - right.submittedAt);
+      history.jobs.splice(0, history.jobs.length - MAX_HISTORY_ENTRIES);
+    }
+    await writeRaw(path, history);
+  });
+}
+async function updateCustomerJob(agentDir, jobEventId, patch) {
+  const path = pathFor(agentDir);
+  return withLock(path, async () => {
+    const history = await readRaw(path);
+    const index = history.jobs.findIndex((job) => job.jobEventId === jobEventId);
+    if (index < 0) {
+      return;
+    }
+    const merged = CustomerJobEntrySchema.parse({ ...history.jobs[index], ...patch });
+    history.jobs[index] = merged;
+    await writeRaw(path, history);
+  });
+}
+async function findCustomerJob(agentDir, jobEventId) {
+  const history = await readCustomerHistory(agentDir);
+  return history.jobs.find((job) => job.jobEventId === jobEventId);
+}
+async function findCustomerJobsByProvider(agentDir, providerPubkey) {
+  const history = await readCustomerHistory(agentDir);
+  return history.jobs.filter((job) => job.providerPubkey === providerPubkey).sort((left, right) => right.completedAt - left.completedAt);
+}
 
 // src/tools/customer.ts
 var PRE_PING_TIMEOUT_MS = 5e3;
@@ -1174,7 +1284,10 @@ var GetJobResultSchema = z.object({
 });
 var ListMyJobsSchema = z.object({
   limit: z.number().int().min(1).max(50).default(20),
-  kind_offset: z.number().int().min(0).max(999).default(DEFAULT_KIND_OFFSET)
+  kind_offset: z.number().int().min(0).max(999).default(DEFAULT_KIND_OFFSET),
+  include_nostr: z.boolean().default(false).describe(
+    "When true, also pull jobs from Nostr relays and merge them with the local cache. Default is false - the local cache is the source of truth and avoids a network roundtrip per call. Use true when looking for jobs submitted from outside this MCP (e.g. the web app) or to recover after a local-cache wipe."
+  )
 });
 var SubmitAndPayJobSchema = z.object({
   input: z.string(),
@@ -1191,13 +1304,6 @@ var BuyCapabilitySchema = z.object({
   max_price_lamports: z.number().int().optional(),
   timeout_secs: z.number().int().min(1).max(600).default(120)
 });
-function decodeNpub(npub) {
-  const decoded = nip19.decode(npub);
-  if (decoded.type !== "npub") {
-    throw new Error(`Expected npub, got ${decoded.type}`);
-  }
-  return decoded.data;
-}
 function providerSolanaAddress(provider, dTag) {
   const cards = provider.cards ?? [];
   const candidates = dTag ? cards.filter(
@@ -1213,6 +1319,48 @@ function providerSolanaAddress(provider, dTag) {
 function wsUrlFor(httpUrl) {
   return httpUrl.replace(/^https:\/\//, "wss://").replace(/^http:\/\//, "ws://");
 }
+async function recordJobOutcome(agent, entry) {
+  if (!agent.agentDir) {
+    return;
+  }
+  try {
+    await appendCustomerJob(agent.agentDir, entry);
+  } catch (e) {
+    logger.warn(
+      { event: "customer_history_write_failed", agent: agent.name, error: String(e) },
+      "failed to write .customer-history.json"
+    );
+  }
+}
+function clipProviderName(name) {
+  if (name === void 0) {
+    return void 0;
+  }
+  return name.length > 200 ? name.slice(0, 200) : name;
+}
+function buildJobCompletionTip(jobId, providerNpub) {
+  return `
+
+Tip: rate this provider with submit_feedback (job_event_id="${jobId}", rating="positive"|"negative"), or save them with add_contact (npub="${providerNpub}").`;
+}
+function classifyJobFailure(message) {
+  return /timed out/i.test(message) ? "timeout" : "failed";
+}
+async function gasHintForCardAsset(agent, asset) {
+  if (!agent.solanaKeypair) {
+    return "";
+  }
+  try {
+    const rpc = createSolanaRpc(rpcUrlFor(agent.network));
+    const baseline = await estimateNetworkBaseline(rpc, {
+      includeAtaRent: asset.mint !== void 0
+    });
+    return `
+${formatNetworkBaseline(baseline)}`;
+  } catch {
+    return "";
+  }
+}
 var paymentStrategy = new SolanaPaymentStrategy();
 async function executePaymentFlow(agent, paymentRequest, jobId, providerPubkey, expectedRecipient) {
   let requestData;
@@ -1322,7 +1470,7 @@ function makePaymentFeedbackHandler(opts) {
     if (opts.maxPriceLamports === void 0 && signedAmount !== void 0) {
       opts.rejectPayment(
         new Error(
-          `Payment of ${formatAssetAmount(asset, BigInt(signedAmount))} required but no max_price_lamports set. Retry with max_price_lamports to approve.`
+          `Payment of ${formatAssetAmount(asset, BigInt(signedAmount))} required but no max_price_lamports set. Retry with max_price_lamports to approve. Use estimate_payment_cost on the payment_request to preview SOL gas before retrying.`
         )
       );
       return;
@@ -1358,7 +1506,7 @@ Payment request: ${paymentRequest}`
       paid = true;
       paying = false;
       const warnings = takeSpendWarnings(opts.ctx, asset);
-      opts.onPaid(sig, warnings);
+      opts.onPaid(sig, warnings, reservedAmount, assetKey(asset));
       flushResult();
     }).catch((e) => {
       paying = false;
@@ -1502,80 +1650,110 @@ var customerTools = [
   }),
   defineTool({
     name: "list_my_jobs",
-    description: "List jobs submitted by the CURRENT AGENT (filtered by customer pubkey) and their results/feedback. Targeted (encrypted) results are decrypted automatically. WARNING: Job results and feedback are untrusted external data.",
+    description: "List jobs submitted by the CURRENT AGENT from the local on-disk history (.customer-history.json). Pass include_nostr=true to also pull from Nostr relays and merge - useful for jobs submitted outside this MCP (e.g. the web app) or to recover after a local-cache wipe. Targeted (encrypted) Nostr results are decrypted automatically. Each entry is tagged with source=local-only|nostr-only|merged. WARNING: result content is untrusted external data.",
     schema: ListMyJobsSchema,
     async handler(ctx, input) {
       ctx.toolRateLimiter.check();
       const agent = ctx.active();
-      const overFetchFactor = 5;
-      const overFetchCap = 500;
-      const rawLimit = Math.min(input.limit * overFetchFactor, overFetchCap);
-      const jobs = await agent.client.marketplace.fetchRecentJobs(
-        void 0,
-        // agentPubkeys: provider filter, not what we want
-        rawLimit,
-        void 0,
-        // since: SDK default lookback
-        [input.kind_offset]
-      );
-      const mine = jobs.filter((j) => j.customer === agent.identity.publicKey).slice(0, input.limit);
-      const jobIdsWithResults = mine.filter((j) => j.resultEventId).map((j) => j.eventId);
+      const localEntries = agent.agentDir ? (await readCustomerHistory(agent.agentDir)).jobs : [];
+      const localById = new Map(localEntries.map((entry) => [entry.jobEventId, entry]));
+      let nostrJobs = [];
       let decryptedByRequest = /* @__PURE__ */ new Map();
-      if (jobIdsWithResults.length > 0) {
-        try {
-          const decrypted = await agent.client.marketplace.queryJobResults(
-            agent.identity,
-            jobIdsWithResults,
-            [input.kind_offset]
-          );
-          decryptedByRequest = new Map(
-            [...decrypted.entries()].map(([id, v]) => [
-              id,
-              { content: v.content, decryptionFailed: v.decryptionFailed }
-            ])
-          );
-        } catch (e) {
-          const message = e instanceof Error ? e.message : String(e);
-          logger.error(
-            { event: "list_my_jobs_query_failed", err: message },
-            "queryJobResults failed"
-          );
+      if (input.include_nostr) {
+        const overFetchFactor = 5;
+        const overFetchCap = 500;
+        const rawLimit = Math.min(input.limit * overFetchFactor, overFetchCap);
+        nostrJobs = (await agent.client.marketplace.fetchRecentJobs(void 0, rawLimit, void 0, [
+          input.kind_offset
+        ])).filter((job) => job.customer === agent.identity.publicKey);
+        const jobIdsWithResults = nostrJobs.filter((job) => job.resultEventId).map((job) => job.eventId);
+        if (jobIdsWithResults.length > 0) {
+          try {
+            const decrypted = await agent.client.marketplace.queryJobResults(
+              agent.identity,
+              jobIdsWithResults,
+              [input.kind_offset]
+            );
+            decryptedByRequest = new Map(
+              [...decrypted.entries()].map(([id, value]) => [
+                id,
+                { content: value.content, decryptionFailed: value.decryptionFailed }
+              ])
+            );
+          } catch (e) {
+            const message = e instanceof Error ? e.message : String(e);
+            logger.error(
+              { event: "list_my_jobs_query_failed", err: message },
+              "queryJobResults failed"
+            );
+          }
         }
       }
+      const nostrById = new Map(nostrJobs.map((job) => [job.eventId, job]));
       let freetextSuspicious = false;
-      const results = mine.map((job) => {
-        const dec = decryptedByRequest.get(job.eventId);
+      const allIds = /* @__PURE__ */ new Set([...localById.keys(), ...nostrById.keys()]);
+      const merged = [...allIds].map((eventId) => {
+        const local = localById.get(eventId);
+        const nostr = nostrById.get(eventId);
+        let source;
+        if (local && nostr) {
+          source = "merged";
+        } else if (local) {
+          source = "local-only";
+        } else {
+          source = "nostr-only";
+        }
         let resultText;
-        if (dec) {
-          if (dec.decryptionFailed) {
-            resultText = "[decryption failed - targeted result not for this agent]";
-          } else {
-            const cleaned = sanitizeInner(dec.content);
+        if (nostr) {
+          const decrypted = decryptedByRequest.get(eventId);
+          if (decrypted) {
+            if (decrypted.decryptionFailed) {
+              resultText = "[decryption failed - targeted result not for this agent]";
+            } else {
+              const cleaned = sanitizeInner(decrypted.content);
+              if (scanForInjections(cleaned, "full")) {
+                freetextSuspicious = true;
+              }
+              resultText = cleaned;
+            }
+          } else if (nostr.result) {
+            const cleaned = sanitizeInner(nostr.result);
             if (scanForInjections(cleaned, "full")) {
               freetextSuspicious = true;
             }
             resultText = cleaned;
           }
-        } else if (job.result) {
-          const cleaned = sanitizeInner(job.result);
+        }
+        if (!resultText && local?.resultPreview) {
+          const cleaned = sanitizeInner(local.resultPreview);
           if (scanForInjections(cleaned, "full")) {
             freetextSuspicious = true;
           }
           resultText = cleaned;
         }
+        const status = nostr?.status ?? local?.status;
+        const capability = nostr?.capability ?? local?.capability;
+        const amount = nostr?.amount ?? local?.paidAmountSubunits;
+        const timestamp = nostr?.createdAt ?? (local ? Math.floor(local.submittedAt / 1e3) : void 0);
         return {
-          event_id: job.eventId,
-          status: sanitizeField(job.status ?? "", 100),
-          capability: sanitizeField(job.capability ?? "", 100),
-          amount: job.amount,
-          timestamp: job.createdAt,
-          result: resultText
+          event_id: eventId,
+          source,
+          status: status !== void 0 ? sanitizeField(String(status), 100) : void 0,
+          capability: capability !== void 0 ? sanitizeField(String(capability), 100) : void 0,
+          amount: amount !== void 0 ? String(amount) : void 0,
+          asset_key: local?.assetKey,
+          timestamp,
+          result: resultText,
+          payment_sig: local?.paymentSig,
+          customer_feedback: local?.customerFeedback
         };
       });
-      const { text: wrapped } = sanitizeUntrusted(JSON.stringify(results, null, 2), "structured", {
+      merged.sort((left, right) => (right.timestamp ?? 0) - (left.timestamp ?? 0));
+      const limited = merged.slice(0, input.limit);
+      const { text: wrapped } = sanitizeUntrusted(JSON.stringify(limited, null, 2), "structured", {
         extraInjectionSignal: freetextSuspicious
       });
-      return textResult(`Found ${results.length} of your jobs:
+      return textResult(`Found ${limited.length} of your jobs:
 ${wrapped}`);
     }
   }),
@@ -1609,6 +1787,7 @@ ${wrapped}`);
           `Provider "${input.provider_npub}" has no Solana payment address for capability "${input.capability}". Cannot verify payment recipient - refusing to proceed. Ask the provider to publish a capability card with a payment address.`
         );
       }
+      const submittedAt = Date.now();
       const jobId = await agent.client.marketplace.submitJobRequest(agent.identity, {
         input: input.input,
         capability: input.capability,
@@ -1616,6 +1795,8 @@ ${wrapped}`);
         kindOffset: input.kind_offset
       });
       let paymentSig;
+      let paidAmountSubunits;
+      let paidAssetKey;
       let paymentWarnings = [];
       try {
         const result = await awaitJobResult(
@@ -1632,8 +1813,10 @@ ${wrapped}`);
               resolveNoWallet: resolve,
               resolveResult: resolve,
               rejectPayment: reject,
-              onPaid: (sig, warnings) => {
+              onPaid: (sig, warnings, amount, assetKey5) => {
                 paymentSig = sig;
+                paidAmountSubunits = amount;
+                paidAssetKey = assetKey5;
                 paymentWarnings = warnings;
                 for (const line of warnings) {
                   logger.warn({ event: "session_spend_threshold", agent: agent.name }, line);
@@ -1663,12 +1846,38 @@ ${sanitized.text}`);
           },
           timeout + 5e3
         );
+        await recordJobOutcome(agent, {
+          jobEventId: jobId,
+          capability: input.capability,
+          providerPubkey,
+          providerName: clipProviderName(provider.name),
+          paidAmountSubunits: paidAmountSubunits?.toString(),
+          assetKey: paidAssetKey,
+          status: "completed",
+          submittedAt,
+          completedAt: Date.now(),
+          resultPreview: result.slice(0, 500),
+          paymentSig
+        });
         const warningBlock = paymentWarnings.length > 0 ? `${paymentWarnings.join("\n")}
 ` : "";
+        const tip = buildJobCompletionTip(jobId, input.provider_npub);
         return textResult(`${warningBlock}event_id=${jobId}
-${result}`);
+${result}${tip}`);
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
+        await recordJobOutcome(agent, {
+          jobEventId: jobId,
+          capability: input.capability,
+          providerPubkey,
+          providerName: clipProviderName(provider.name),
+          paidAmountSubunits: paidAmountSubunits?.toString(),
+          assetKey: paidAssetKey,
+          status: classifyJobFailure(msg),
+          submittedAt,
+          completedAt: Date.now(),
+          paymentSig
+        });
         const paid = paymentSig ? ` Payment already sent (sig=${paymentSig}) - use get_job_result with event_id="${jobId}" to retrieve once ready.` : "";
         const warningBlock = paymentWarnings.length > 0 ? `${paymentWarnings.join("\n")}
 ` : "";
@@ -1718,11 +1927,12 @@ ${result}`);
         );
       }
       if (price > 0 && input.max_price_lamports === void 0) {
+        const gasLine = await gasHintForCardAsset(agent, cardAsset);
         return {
           content: [
             {
               type: "text",
-              text: `Capability "${input.capability}" from "${provider.name || input.provider_npub}" costs ${formatAssetAmount(cardAsset, BigInt(price))}.
+              text: `Capability "${input.capability}" from "${provider.name || input.provider_npub}" costs ${formatAssetAmount(cardAsset, BigInt(price))}.${gasLine}
 
 To confirm, call buy_capability again with max_price_lamports set (e.g. ${price} or higher).`
             }
@@ -1735,12 +1945,15 @@ To confirm, call buy_capability again with max_price_lamports set (e.g. ${price}
           `Provider "${input.provider_npub}" has no Solana payment address for capability "${input.capability}". Cannot verify payment recipient.`
         );
       }
+      const submittedAt = Date.now();
       const jobId = await agent.client.marketplace.submitJobRequest(agent.identity, {
         input: input.input || "",
         capability: dTag,
         providerPubkey
       });
       let paymentSig;
+      let paidAmountSubunits;
+      let paidAssetKey;
       let paymentWarnings = [];
       try {
         const result = await awaitJobResult(
@@ -1757,8 +1970,10 @@ To confirm, call buy_capability again with max_price_lamports set (e.g. ${price}
               resolveNoWallet: resolve,
               resolveResult: resolve,
               rejectPayment: reject,
-              onPaid: (sig, warnings) => {
+              onPaid: (sig, warnings, amount, assetKey5) => {
                 paymentSig = sig;
+                paidAmountSubunits = amount;
+                paidAssetKey = assetKey5;
                 paymentWarnings = warnings;
                 for (const line of warnings) {
                   logger.warn({ event: "session_spend_threshold", agent: agent.name }, line);
@@ -1790,12 +2005,38 @@ ${sanitized.text}`
           },
           timeout + 5e3
         );
+        await recordJobOutcome(agent, {
+          jobEventId: jobId,
+          capability: dTag,
+          providerPubkey,
+          providerName: clipProviderName(provider.name),
+          paidAmountSubunits: paidAmountSubunits?.toString(),
+          assetKey: paidAssetKey,
+          status: "completed",
+          submittedAt,
+          completedAt: Date.now(),
+          resultPreview: result.slice(0, 500),
+          paymentSig
+        });
         const warningBlock = paymentWarnings.length > 0 ? `${paymentWarnings.join("\n")}
 ` : "";
+        const tip = buildJobCompletionTip(jobId, input.provider_npub);
         return textResult(`${warningBlock}event_id=${jobId}
-${result}`);
+${result}${tip}`);
       } catch (e) {
         const msg = e instanceof Error ? e.message : String(e);
+        await recordJobOutcome(agent, {
+          jobEventId: jobId,
+          capability: dTag,
+          providerPubkey,
+          providerName: clipProviderName(provider.name),
+          paidAmountSubunits: paidAmountSubunits?.toString(),
+          assetKey: paidAssetKey,
+          status: classifyJobFailure(msg),
+          submittedAt,
+          completedAt: Date.now(),
+          paymentSig
+        });
         const paid = paymentSig ? ` Payment already sent (sig=${paymentSig}) - use get_job_result with event_id="${jobId}" to retrieve once ready.` : "";
         const warningBlock = paymentWarnings.length > 0 ? `${paymentWarnings.join("\n")}
 ` : "";
@@ -1847,6 +2088,111 @@ ${text}`);
     }
   })
 ];
+var CONTACTS_FILENAME = ".contacts.json";
+var ContactSchema = z.object({
+  pubkey: z.string().regex(/^[a-f0-9]{64}$/),
+  npub: z.string().min(1).max(80),
+  name: z.string().max(200).optional(),
+  addedAt: z.number().int().nonnegative(),
+  lastJobAt: z.number().int().nonnegative().optional(),
+  jobCount: z.number().int().nonnegative(),
+  lastCapability: z.string().max(200).optional(),
+  note: z.string().max(500).optional()
+}).strict();
+var ContactsSchema = z.object({
+  version: z.literal(1),
+  contacts: z.array(ContactSchema)
+}).strict();
+var EMPTY2 = { version: 1, contacts: [] };
+var writeLocks2 = /* @__PURE__ */ new Map();
+function withLock2(path, fn) {
+  const previous = writeLocks2.get(path) ?? Promise.resolve();
+  const next = previous.then(fn, fn);
+  writeLocks2.set(
+    path,
+    next.finally(() => {
+      if (writeLocks2.get(path) === next) {
+        writeLocks2.delete(path);
+      }
+    })
+  );
+  return next;
+}
+function pathFor2(agentDir) {
+  return join(agentDir, CONTACTS_FILENAME);
+}
+async function readRaw2(path) {
+  let raw;
+  try {
+    raw = await readFile(path, "utf-8");
+  } catch {
+    return { ...EMPTY2, contacts: [] };
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    const result = ContactsSchema.safeParse(parsed);
+    return result.success ? result.data : { ...EMPTY2, contacts: [] };
+  } catch {
+    return { ...EMPTY2, contacts: [] };
+  }
+}
+async function writeRaw2(path, contacts) {
+  const body = JSON.stringify(contacts, null, 2) + "\n";
+  await writeFileAtomic$1(path, body, 384);
+}
+async function readContacts(agentDir) {
+  return readRaw2(pathFor2(agentDir));
+}
+async function upsertContact(agentDir, input) {
+  const path = pathFor2(agentDir);
+  return withLock2(path, async () => {
+    const data = await readRaw2(path);
+    const index = data.contacts.findIndex((existing) => existing.pubkey === input.pubkey);
+    let merged;
+    if (index >= 0) {
+      const existing = data.contacts[index];
+      merged = ContactSchema.parse({
+        ...existing,
+        npub: input.npub,
+        name: input.name ?? existing.name,
+        note: input.note ?? existing.note,
+        lastJobAt: input.lastJobAt ?? existing.lastJobAt,
+        lastCapability: input.lastCapability ?? existing.lastCapability,
+        jobCount: input.jobCount ?? existing.jobCount + 1
+      });
+      data.contacts[index] = merged;
+    } else {
+      merged = ContactSchema.parse({
+        pubkey: input.pubkey,
+        npub: input.npub,
+        name: input.name,
+        note: input.note,
+        addedAt: Date.now(),
+        lastJobAt: input.lastJobAt,
+        lastCapability: input.lastCapability,
+        jobCount: input.jobCount ?? 0
+      });
+      data.contacts.push(merged);
+    }
+    await writeRaw2(path, data);
+    return merged;
+  });
+}
+async function removeContact(agentDir, pubkey) {
+  const path = pathFor2(agentDir);
+  return withLock2(path, async () => {
+    const data = await readRaw2(path);
+    const before = data.contacts.length;
+    data.contacts = data.contacts.filter((existing) => existing.pubkey !== pubkey);
+    if (data.contacts.length === before) {
+      return false;
+    }
+    await writeRaw2(path, data);
+    return true;
+  });
+}
+
+// src/tools/discovery.ts
 var SEARCH_PING_TIMEOUT_MS = 3e3;
 var STOP_WORDS = /* @__PURE__ */ new Set([
   "a",
@@ -1983,6 +2329,9 @@ var SearchAgentsSchema = z.object({
   max_price_lamports: z.number().int().optional(),
   include_offline: z.boolean().default(false).describe(
     "If true, skip the live online check and return agents regardless of reachability. Default: false - only currently-online agents are returned."
+  ),
+  contacts_only: z.boolean().default(false).describe(
+    "If true, restrict results to providers saved in the active agent's .contacts.json. Each returned item gains a `last_worked_at` field."
   )
 });
 var ListCapabilitiesSchema = z.object({});
@@ -1993,13 +2342,31 @@ var discoveryTools = [
     description: "Search AI agents currently online on elisym. `capabilities` is a hard OR-filter of substring tokens from the user's request (never invent synonyms). `query` is optional re-ranking; omit if not needed. Offline agents are excluded by default - pass include_offline=true only when debugging.",
     schema: SearchAgentsSchema,
     async handler(ctx, input) {
-      const { capabilities, query, max_price_lamports, include_offline } = input;
+      const { capabilities, query, max_price_lamports, include_offline, contacts_only } = input;
       if (capabilities.length > MAX_CAPABILITIES) {
         return errorResult(`Too many capabilities (max ${MAX_CAPABILITIES})`);
       }
       const agent = ctx.active();
+      let lastWorkedAtByPubkey = /* @__PURE__ */ new Map();
+      if (contacts_only) {
+        if (!agent.agentDir) {
+          return textResult(
+            "contacts_only=true requires a persistent agent (no on-disk directory for the active agent)."
+          );
+        }
+        const data = await readContacts(agent.agentDir);
+        if (data.contacts.length === 0) {
+          return textResult(
+            "No contacts saved yet. Use add_contact (or rate a job positively with submit_feedback and then add_contact) before searching with contacts_only=true."
+          );
+        }
+        lastWorkedAtByPubkey = new Map(
+          data.contacts.map((contact) => [contact.pubkey, contact.lastJobAt ?? contact.addedAt])
+        );
+      }
       const agents = await agent.client.discovery.fetchAgents(agent.network);
-      let filtered = agents.filter(
+      let filtered = contacts_only ? agents.filter((a) => lastWorkedAtByPubkey.has(a.pubkey)) : agents;
+      filtered = filtered.filter(
         (a) => a.cards.some(
           (card) => capabilities.some(
             (cap) => card.capabilities?.some((c) => c.toLowerCase().includes(cap.toLowerCase())) || card.name?.toLowerCase().includes(cap.toLowerCase()) || card.description?.toLowerCase().includes(cap.toLowerCase())
@@ -2070,7 +2437,8 @@ var discoveryTools = [
             network: card.payment?.network
           };
         }),
-        supported_kinds: a.supportedKinds
+        supported_kinds: a.supportedKinds,
+        last_worked_at: contacts_only ? lastWorkedAtByPubkey.get(a.pubkey) : void 0
       }));
       const { text } = sanitizeUntrusted(JSON.stringify(results, null, 2), "structured");
       return textResult(text);
@@ -2119,6 +2487,184 @@ ${text}`);
     }
   })
 ];
+var SubmitFeedbackSchema = z.object({
+  job_event_id: z.string().min(1).max(128).describe("Event ID returned by submit_and_pay_job, buy_capability, or create_job."),
+  rating: z.enum(["positive", "negative"]),
+  provider_npub: z.string().optional().describe(
+    "Provider npub. Optional when the job is in local history (.customer-history.json); required when feedback is submitted for a job submitted from outside this MCP."
+  )
+});
+var AddContactSchema = z.object({
+  npub: z.string().min(1).max(MAX_NPUB_LEN),
+  name: z.string().max(200).optional(),
+  note: z.string().max(500).optional()
+});
+var RemoveContactSchema = z.object({
+  npub: z.string().min(1).max(MAX_NPUB_LEN)
+});
+var ListContactsSchema = z.object({
+  limit: z.number().int().min(1).max(200).default(50)
+});
+function npubFromHex(pubkey) {
+  return nip19.npubEncode(pubkey);
+}
+var feedbackContactsTools = [
+  defineTool({
+    name: "submit_feedback",
+    description: 'Rate a completed job (mirrors the web app \u{1F44D}/\u{1F44E} buttons). Publishes a NIP-90 kind 7000 feedback event with rating="1" (positive) or "0" (negative). Idempotent on (job_event_id, rating) - calling twice with the same rating is a no-op. After a positive rating, the response suggests calling add_contact to save the provider for future search_agents queries.',
+    schema: SubmitFeedbackSchema,
+    async handler(ctx, input) {
+      ctx.toolRateLimiter.check();
+      checkLen("job_event_id", input.job_event_id, MAX_EVENT_ID_LEN);
+      if (input.provider_npub) {
+        checkLen("provider_npub", input.provider_npub, MAX_NPUB_LEN);
+      }
+      const agent = ctx.active();
+      const localEntry = agent.agentDir ? await findCustomerJob(agent.agentDir, input.job_event_id) : void 0;
+      let providerPubkey = localEntry?.providerPubkey;
+      if (!providerPubkey && input.provider_npub) {
+        try {
+          providerPubkey = decodeNpub(input.provider_npub);
+        } catch (e) {
+          return errorResult(
+            `Invalid provider_npub: ${e instanceof Error ? e.message : String(e)}`
+          );
+        }
+      }
+      if (!providerPubkey) {
+        return errorResult(
+          `Job "${input.job_event_id}" not found in local history. Pass provider_npub explicitly to rate a job submitted from outside this MCP.`
+        );
+      }
+      if (localEntry?.customerFeedback === input.rating) {
+        return textResult(`Already rated as ${input.rating}.`);
+      }
+      const capability = localEntry?.capability;
+      const positive = input.rating === "positive";
+      try {
+        await agent.client.marketplace.submitFeedback(
+          agent.identity,
+          input.job_event_id,
+          providerPubkey,
+          positive,
+          capability
+        );
+      } catch (e) {
+        return errorResult(
+          `Failed to publish feedback: ${e instanceof Error ? e.message : String(e)}`
+        );
+      }
+      if (agent.agentDir && localEntry) {
+        await updateCustomerJob(agent.agentDir, input.job_event_id, {
+          customerFeedback: input.rating
+        }).catch(() => {
+        });
+      }
+      const npubForTip = input.provider_npub ?? npubFromHex(providerPubkey);
+      if (positive) {
+        return textResult(
+          `Feedback recorded (rating=positive). Save this provider for future searches? Use add_contact (npub="${npubForTip}").`
+        );
+      }
+      return textResult("Feedback recorded (rating=negative).");
+    }
+  }),
+  defineTool({
+    name: "add_contact",
+    description: "Add a provider to the active agent's contacts list (.contacts.json). When the provider has prior jobs in the local history, the contact is enriched with jobCount, lastJobAt, and lastCapability. Idempotent: re-calling with the same npub updates name/note in place without duplicating the entry.",
+    schema: AddContactSchema,
+    async handler(ctx, input) {
+      ctx.toolRateLimiter.check();
+      checkLen("npub", input.npub, MAX_NPUB_LEN);
+      const agent = ctx.active();
+      if (!agent.agentDir) {
+        return errorResult(
+          "Cannot save contacts: the active agent is ephemeral (no on-disk directory). Create a persistent agent first with create_agent."
+        );
+      }
+      let pubkey;
+      try {
+        pubkey = decodeNpub(input.npub);
+      } catch (e) {
+        return errorResult(`Invalid npub: ${e instanceof Error ? e.message : String(e)}`);
+      }
+      const history = await findCustomerJobsByProvider(agent.agentDir, pubkey);
+      const last = history[0];
+      const cleanName = input.name !== void 0 ? sanitizeField(input.name, 200) : void 0;
+      const cleanNote = input.note !== void 0 ? sanitizeField(input.note, 500) : void 0;
+      const fallbackProviderName = last?.providerName !== void 0 ? sanitizeField(last.providerName, 200) : void 0;
+      const contact = await upsertContact(agent.agentDir, {
+        pubkey,
+        npub: input.npub,
+        name: cleanName ?? fallbackProviderName,
+        note: cleanNote,
+        lastJobAt: last?.completedAt,
+        lastCapability: last?.capability,
+        jobCount: history.length
+      });
+      const lines = [
+        `Saved contact ${contact.npub}.`,
+        contact.name ? `  name: ${contact.name}` : null,
+        contact.lastCapability ? `  last capability: ${contact.lastCapability}` : null,
+        contact.jobCount > 0 ? `  prior jobs: ${contact.jobCount}` : null
+      ].filter((line) => line !== null);
+      return textResult(lines.join("\n"));
+    }
+  }),
+  defineTool({
+    name: "remove_contact",
+    description: "Remove a provider from the active agent's contacts list.",
+    schema: RemoveContactSchema,
+    async handler(ctx, input) {
+      ctx.toolRateLimiter.check();
+      checkLen("npub", input.npub, MAX_NPUB_LEN);
+      const agent = ctx.active();
+      if (!agent.agentDir) {
+        return errorResult("Active agent is ephemeral; nothing to remove.");
+      }
+      let pubkey;
+      try {
+        pubkey = decodeNpub(input.npub);
+      } catch (e) {
+        return errorResult(`Invalid npub: ${e instanceof Error ? e.message : String(e)}`);
+      }
+      const removed = await removeContact(agent.agentDir, pubkey);
+      return removed ? textResult(`Removed contact ${input.npub}.`) : textResult(`No contact found for ${input.npub}.`);
+    }
+  }),
+  defineTool({
+    name: "list_contacts",
+    description: "List providers saved in the active agent's .contacts.json, newest activity first. Use search_agents with contacts_only=true to combine this with online/capability filters.",
+    schema: ListContactsSchema,
+    async handler(ctx, input) {
+      ctx.toolRateLimiter.check();
+      const agent = ctx.active();
+      if (!agent.agentDir) {
+        return textResult(
+          "Active agent is ephemeral; no on-disk contacts. Create a persistent agent first."
+        );
+      }
+      const data = await readContacts(agent.agentDir);
+      const sorted = [...data.contacts].sort((left, right) => {
+        const leftKey = left.lastJobAt ?? left.addedAt;
+        const rightKey = right.lastJobAt ?? right.addedAt;
+        return rightKey - leftKey;
+      });
+      const limited = sorted.slice(0, input.limit).map((contact) => ({
+        npub: contact.npub,
+        name: contact.name !== void 0 ? sanitizeField(contact.name, 200) : void 0,
+        note: contact.note !== void 0 ? sanitizeField(contact.note, 500) : void 0,
+        added_at: contact.addedAt,
+        last_job_at: contact.lastJobAt,
+        last_capability: contact.lastCapability !== void 0 ? sanitizeField(contact.lastCapability, 200) : void 0,
+        job_count: contact.jobCount
+      }));
+      const { text: wrapped } = sanitizeUntrusted(JSON.stringify(limited, null, 2), "structured");
+      return textResult(`${limited.length} contact(s):
+${wrapped}`);
+    }
+  })
+];
 var GetBalanceSchema = z.object({});
 var EstimatePaymentCostSchema = z.object({
   payment_request: z.string().describe(
@@ -2625,7 +3171,8 @@ var allTools = [
   ...customerTools,
   ...walletTools,
   ...dashboardTools,
-  ...agentTools
+  ...agentTools,
+  ...feedbackContactsTools
 ];
 var toolMap = /* @__PURE__ */ new Map();
 for (const tool of allTools) {