feat(examples): refresh Perplexity output through the retained grant (#103)

Author: callumflack

examples/perplexity-demo/README.md

@@ -129,3 +129,19 @@ Use the maintained [connection verification evidence rules](https://github.com/v
 Keep private titles and raw payloads outside Git/Linear. A successful server access log with no saved demo result is a failed consumer-delivery attempt, not end-to-end success. Preserve its receipt and cost; a fresh charged attempt requires an explicit operator decision rather than automatic replacement. Compare saved content to what the browser actually displays, and retain failure attempts rather than relabelling them. A grant's chain finalization and consumer acknowledgement are separate observations.
 
 [Motel composition guidance](https://github.com/vana-com/unity-surfaces/blob/a87843f90b9b570ce493e769d348b1a869a9ebae/.agents/skills/us-verify-with-motel/SKILL.md) is optional diagnosis. Its existing exporter is Desktop-specific and does not capture this example. Use existing request/payment/save evidence first; add app-owned, metadata-only probes only for a concrete unresolved failure. Do not launch Desktop, upgrade Personal Server or build an observability programme for this milestone.
+
+## Iterate through the same grant — BUI-932
+
+After the first result is saved, displayed and acknowledged, **Read latest** performs a fresh SDK read using the owner/app/network/grant/server binding retained privately by the backend. It accepts no grant, server, scope or request overrides from the browser and does not reopen the completed Direct request. The backend rechecks the live grant and owner-bound server. If access has expired or been revoked, the saved list stays visible and **Review access again** is available. Funding and transient server errors remain read/funding problems.
+
+Every deliberately fresh read can incur the current capped test-VANA fee. Earlier successful receipts remain in private history; a failed or uncertain fresh attempt reuses its own receipt instead of authorizing another fee. A delivered body that has not been decoded/saved, or a saved response lost before the browser received it, is recovered before another paid read. Acknowledgement follows rendering of the recovered/new revision. The BUI-931 ledger is adopted only when its saved, acknowledged revision matches its retained received body; uncertain legacy payments are not relabelled as successful.
+
+To prove a connector change:
+
+1. Record one real conversation's stable ID and current title in private evidence. Keep the same app, grant, owner, network and conversations scope.
+2. In an isolated, unpublished checkout of the **same connector version**, edit `connectors/perplexity/parsers.ts` so `conversationRecord` prefixes only that record's returned title with `CLI edit — `. Keep its ID and scope unchanged and respect the title's 500-character bound. Do not edit exported JSON, the app's saved list or synthetic fixtures.
+3. Rerun `vana connect perplexity --from /path/to/edited/data-connectors --streams conversations --network moksha --yes --ipc`. The selected 0.1.1 conversations-only path emits its listed conversations on every run; do not clear cursors, bypass refresh limits or import messages merely to force an update. Keep the CLI receipt and prove that the actual emitted record contains the changed title.
+4. Verify ingestion and serving of the changed payload on the same owner-bound server. A new version number alone is insufficient. Record any manual setup/copy assistance explicitly; a development-wallet copy is not automatic CLI delivery.
+5. After the original Direct request is complete, click **Read latest**. Prove a new saved revision with the changed title in the real demo, using the same grant, then observe acknowledgement after rendering. Record the current fee, preserved previous receipts and total authorized amount. Refresh the page to verify the saved result survives.
+
+The local connector edit is an acceptance experiment, not a connector publication or upstream feature. Keep its private record ID and real data outside this repository. Mainnet, native per-account delivery, publishing, review and the public Registry remain separate.

examples/perplexity-demo/src/app/api/latest/route.ts

@@ -0,0 +1,31 @@
+import { shelf } from "../../../config.js";
+import { DeliveryError } from "../../../server/delivery.js";
+import { failure, json, sameOrigin, session } from "../../../server/http.js";
+
+/** A fresh read uses only the binding retained by the server after initial delivery. */
+export async function POST(request: Request) {
+  try {
+    sameOrigin(request);
+    let body: unknown;
+    try {
+      body = await request.json();
+    } catch {
+      throw new DeliveryError("invalid_input", "Invalid JSON body.", 400);
+    }
+    if (
+      !body ||
+      typeof body !== "object" ||
+      Array.isArray(body) ||
+      Object.keys(body).length
+    ) {
+      throw new DeliveryError(
+        "invalid_input",
+        "Read latest accepts no grant, server, scope or request overrides.",
+        400,
+      );
+    }
+    return json(await shelf.read(session(request)));
+  } catch (error) {
+    return failure(error);
+  }
+}

examples/perplexity-demo/src/components/ConnectFlow.tsx

@@ -42,6 +42,9 @@ export default function ConnectFlow() {
   const connectionGeneration = useRef(0);
   const acknowledged = !!saved && acknowledgedRevision === saved.revision;
   const [ackError, setAckError] = useState<string>();
+  const [refreshing, setRefreshing] = useState(false);
+  const [refreshError, setRefreshError] = useState<string>();
+  const [reviewRequired, setReviewRequired] = useState(false);
   const { state, start, reset, retryRead } = useDirectVanaConnect<
     NonNullable<Connection["saved"]>
   >({
@@ -124,6 +127,50 @@ export default function ConnectFlow() {
     }
   }
 
+  async function readLatest() {
+    const generation = connectionGeneration.current;
+    setRefreshing(true);
+    setRefreshError(undefined);
+    setReviewRequired(false);
+    try {
+      const response = await fetch("/api/latest", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: "{}",
+      });
+      if (!response.ok && connectionGeneration.current === generation) {
+        const refusal = await response
+          .clone()
+          .json()
+          .catch(() => undefined);
+        setReviewRequired(
+          [401, 403].includes(response.status) ||
+            ["approval_required", "grant_invalid", "grant_refused"].includes(
+              refusal?.code,
+            ),
+        );
+      }
+      const result =
+        await checkedResponse<
+          ApprovedDataResult<NonNullable<Connection["saved"]>>
+        >(response);
+      if (connectionGeneration.current !== generation) return;
+      setSaved(result.data);
+      setAcknowledgedRevision(undefined);
+      setAckError(undefined);
+      setReviewRequired(false);
+    } catch (error) {
+      if (connectionGeneration.current !== generation) return;
+      setRefreshError(
+        error instanceof Error
+          ? error.message
+          : "The latest read did not finish.",
+      );
+    } finally {
+      if (connectionGeneration.current === generation) setRefreshing(false);
+    }
+  }
+
   // Effects run after the saved list has committed to the DOM.
   useEffect(() => {
     displayedRevision.current = saved?.revision;
@@ -160,9 +207,13 @@ export default function ConnectFlow() {
               onClick={() => {
                 connectionGeneration.current++;
                 setAckError(undefined);
+                setRefreshError(undefined);
+                setReviewRequired(false);
+                setRefreshing(false);
                 void start();
               }}
               className="btn-primary full-width"
+              disabled={refreshing}
             >
               Connect with Vana
             </button>
@@ -261,6 +312,32 @@ export default function ConnectFlow() {
             )}
           </>
         )}
+        {saved && (
+          <>
+            <button
+              type="button"
+              className="btn-primary full-width"
+              disabled={
+                refreshing ||
+                !acknowledged ||
+                !["idle", "done", "error"].includes(state.type)
+              }
+              onClick={() => void readLatest()}
+            >
+              {refreshing ? "Reading latest…" : "Read latest"}
+            </button>
+            {refreshError && (
+              <p className="text-error" role="alert">
+                Your saved list is still available. {refreshError}
+              </p>
+            )}
+            {reviewRequired && state.type !== "idle" && (
+              <button type="button" className="btn-ghost" onClick={reset}>
+                Review access again
+              </button>
+            )}
+          </>
+        )}
         {ackError && (
           <>
             <p className="text-error" role="alert">

examples/perplexity-demo/src/server/delivery.ts

@@ -123,9 +123,16 @@ export function createShelf(config: DeliveryConfig) {
   const store = new ShelfStore(config.storageDirectory);
   const payments = new ShelfStore(`${config.storageDirectory}/payments`);
   interface PaymentLedger {
+    format?: number;
     spent: string;
     payment?: { header: string; operation: string; amount: string };
-    received?: { revision: string; receivedAt: string; body: unknown };
+    received?: {
+      revision: string;
+      receivedAt: string;
+      body: unknown;
+      paymentHeaderHash?: string;
+    };
+    history?: { header: string; operation: string; amount: string }[];
   }
   function paymentPolicy(amount: bigint, spent: bigint) {
     if (!config.allowPayment || !config.maxFee || !config.maxTotal)
@@ -163,21 +170,27 @@ export function createShelf(config: DeliveryConfig) {
     return state;
   }
 
-  async function liveBinding(state: Connection) {
+  async function liveBinding(state: Connection, requireCompleted = false) {
     const status = await access.getAccessRequestStatus(state.requestId);
     if (!["approved", "ready_for_read", "completed"].includes(status.status)) {
       throw new DeliveryError(
         "approval_required",
         `The request is ${status.status}. Review access in Vana.`,
       );
     }
+    if (requireCompleted && status.status !== "completed")
+      throw new DeliveryError(
+        "delivery_incomplete",
+        "Confirm the original delivery before reading latest.",
+      );
     const binding = state.binding;
     const grantId = binding?.grantId ?? status.grantId;
     const serverUrl = binding?.serverUrl ?? status.personalServerUrl;
     if (
       !grantId ||
       !serverUrl ||
-      !status.scopes?.includes(SCOPE) ||
+      ((!binding || status.status !== "completed") &&
+        !status.scopes?.includes(SCOPE)) ||
       (status.grantId && status.grantId !== grantId) ||
       (status.personalServerUrl && status.personalServerUrl !== serverUrl)
     ) {
@@ -299,7 +312,22 @@ export function createShelf(config: DeliveryConfig) {
         // A lost response can be recovered without another paid read.
         if (requestId && state.saved)
           return { scope: SCOPE, data: state.saved };
-        const grant = await liveBinding(state);
+        // Recover a saved response lost in transport before attempting another paid read.
+        if (
+          !requestId &&
+          state.saved &&
+          state.acknowledged !== state.saved.revision
+        )
+          return { scope: SCOPE, data: state.saved };
+        if (
+          !requestId &&
+          (!state.saved || state.acknowledged !== state.saved.revision)
+        )
+          throw new DeliveryError(
+            "delivery_incomplete",
+            "Save, display and confirm the initial delivery before reading latest.",
+          );
+        const grant = await liveBinding(state, !requestId);
         await store.save(token, state);
         const binding = state.binding!;
         const ledgerKey = createHash("sha256")
@@ -315,8 +343,34 @@ export function createShelf(config: DeliveryConfig) {
           .digest("hex");
         return payments.exclusive(ledgerKey, async () => {
           const ledger = (await payments.read<PaymentLedger>(ledgerKey)) ?? {
+            format: 2,
             spent: "0",
           };
+          if (ledger.format !== undefined && ledger.format !== 2)
+            throw new DeliveryError(
+              "storage_version",
+              "This payment store needs a compatible demo version.",
+            );
+          if (ledger.format === undefined) {
+            // BUI-931 had no fresh-read endpoint: an acknowledged saved revision
+            // matching its received body proves which existing header delivered it.
+            if (
+              ledger.payment &&
+              ledger.received &&
+              state.saved?.revision === ledger.received.revision &&
+              state.acknowledged === state.saved.revision &&
+              JSON.stringify(state.saved.threads) ===
+                JSON.stringify(threadsFrom(ledger.received.body))
+            ) {
+              ledger.received.paymentHeaderHash = createHash("sha256")
+                .update(ledger.payment.header)
+                .digest("hex");
+            }
+            if (!ledger.received || ledger.received.paymentHeaderHash) {
+              ledger.format = 2;
+              await payments.save(ledgerKey, ledger);
+            }
+          }
           async function saveReceived() {
             const received = ledger.received!;
             state.saved = {
@@ -328,7 +382,15 @@ export function createShelf(config: DeliveryConfig) {
             return { scope: SCOPE, data: state.saved };
           }
           // Recover a delivered body after decoder/save failure without another paid read.
-          if (requestId && ledger.received) return saveReceived();
+          if (
+            ledger.received &&
+            (requestId || ledger.received.revision !== state.saved?.revision)
+          )
+            return saveReceived();
+          const previousDelivered =
+            !!ledger.payment &&
+            ledger.received?.paymentHeaderHash ===
+              createHash("sha256").update(ledger.payment.header).digest("hex");
           let challengeOperation: string | undefined;
           const fetchRead: PersonalServerFetch = async (input, init) => {
             const headers = { ...init.headers };
@@ -344,6 +406,7 @@ export function createShelf(config: DeliveryConfig) {
                 Buffer.from(outgoing, "base64").toString("utf8"),
               );
               const amount: string = payment.payload.message.amount;
+              if (ledger.payment) (ledger.history ??= []).push(ledger.payment);
               ledger.payment = {
                 header: outgoing,
                 operation: challengeOperation,
@@ -352,7 +415,7 @@ export function createShelf(config: DeliveryConfig) {
               ledger.spent = (BigInt(ledger.spent) + BigInt(amount)).toString();
               // Persist before transmission: an uncertain response must not authorize another fee.
               await payments.save(ledgerKey, ledger);
-            } else if (ledger.payment) {
+            } else if (ledger.payment && (requestId || !previousDelivered)) {
               paymentPolicy(
                 BigInt(ledger.payment.amount),
                 BigInt(ledger.spent),
@@ -403,9 +466,7 @@ export function createShelf(config: DeliveryConfig) {
               const operation = `${required.opId}:${required.accessRecord?.dataPointId ?? ""}:${required.accessRecord?.version ?? ""}`;
               if (
                 ledger.payment &&
-                (outgoing ||
-                  ledger.payment.operation === operation ||
-                  !required.accessRecord)
+                (outgoing || requestId || !previousDelivered)
               )
                 throw new DeliveryError(
                   "payment_unconfirmed",
@@ -457,6 +518,9 @@ export function createShelf(config: DeliveryConfig) {
             revision: randomUUID(),
             receivedAt: new Date().toISOString(),
             body: result.data,
+            paymentHeaderHash: ledger.payment
+              ? createHash("sha256").update(ledger.payment.header).digest("hex")
+              : undefined,
           };
           await payments.save(ledgerKey, ledger);
           return saveReceived();