@letsping/sdk 0.1.6 → 0.2.1

package/README.md

@@ -8,6 +8,7 @@ LetsPing is a behavioral firewall and Human-in-the-Loop (HITL) infrastructure la
 - **The Behavioral Shield:** Silently profiles your agent's execution paths via Markov Chains. Automatically intercepts 0-probability reasoning anomalies (hallucinations/prompt injections).
 - **Cryo-Sleep State Parking:** Pauses execution and securely uploads massive agent states directly to storage using Signed URLs, entirely bypassing serverless timeouts and webhook payload limits.
 - **Smart-Accept Drift Adaptation:** Approval decisions mathematically alter the baseline. Old unused reasoning paths decay automatically via Exponential Moving Average (EMA).
+- **Agent Identity & Escrow Helpers:** Optional HMAC-based helpers (`signAgentCall`, `verifyEscrow`, `chainHandoff`) for cryptographically linking agent calls and handoffs to LetsPing requests.
 
 ## Requirements
 - Node.js 18+
@@ -22,6 +23,27 @@ npm install @letsping/sdk
 
 ## Usage
 
+### Minimal drop-in example
+
+The fastest way to see your first approval in the dashboard:
+
+```ts
+import { LetsPing } from "@letsping/sdk";
+
+const apiKey = process.env.LETSPING_API_KEY;
+if (!apiKey) throw new Error("Missing LETSPING_API_KEY env var.");
+
+const lp = new LetsPing(apiKey);
+
+const decision = await lp.ask({
+  service: "billing-agent",
+  action: "refund_user",
+  payload: { user_id: "u_123", amount: 100 },
+});
+```
+
+Every example in this README follows the same pattern: **either pass the key explicitly or rely on `LETSPING_API_KEY` via env**.
+
 ### Blocking Request (`ask`)
 
 Execution suspends until the request is approved, rejected, or times out.
@@ -34,7 +56,7 @@ const lp = new LetsPing(process.env.LETSPING_API_KEY!);
 async function processRefund(userId: string, amount: number) {
   try {
     const decision = await lp.ask({
-      service: "billing-service",
+      service: "billing-agent",
       action: "refund_user",
       priority: "high",
       payload: { userId, amount },
@@ -92,36 +114,115 @@ const { id } = await lp.defer({
 console.log(`Approval request queued → ${id}`);
 ```
 
-### Webhook Rehydration (Framework Agnostic)
-LetsPing does **not** magically inject state back into your framework natively. You must handle the webhook and rehydrate your specific framework manually.
+### Webhook Rehydration (Next.js Example)
+
+When you pass `state_snapshot` to `ask` / `defer`, the SDK:
+
+- Encrypts the snapshot with either `LETSPING_ENCRYPTION_KEY` or a one‑time DEK.
+- Uploads it directly to your storage bucket using a signed URL.
+- Includes a `state_download_url` (and DEK) in subsequent webhooks.
+
+You can use the built‑in `webhookHandler` to validate and hydrate webhooks in a Next.js App Router route:
 
 ```typescript
-// app/api/webhook/letsping/route.ts
-if (body.status === "APPROVED") {
-    let hydratedState = null;
-    if (body.state_download_url) {
-        const res = await fetch(body.state_download_url);
-        hydratedState = lp._decrypt(await res.json());
-    }
-    // Manually push `hydratedState` back into your LangGraph/Vercel thread
+// Example Next.js App Router route
+import { NextRequest, NextResponse } from "next/server";
+import { LetsPing } from "@letsping/sdk";
+
+const lp = new LetsPing();
+const WEBHOOK_SECRET = process.env.LETSPING_WEBHOOK_SECRET!;
+
+export async function POST(req: NextRequest) {
+  const rawBody = await req.text();
+  const signature = req.headers.get("x-letsping-signature") || "";
+
+  try {
+    const { id, event, data, state_snapshot } = await lp.webhookHandler(
+      rawBody,
+      signature,
+      WEBHOOK_SECRET
+    );
+
+    // At this point:
+    // - `data` contains the decision payload (status, payload, patched_payload, metadata, etc.)
+    // - `state_snapshot` contains your decrypted agent state, if Cryo-Sleep was used.
+
+    await handleDecision({ id, event, data, state_snapshot });
+
+    return NextResponse.json({ ok: true });
+  } catch (err: any) {
+    console.error("LetsPing webhook error:", err);
+    return NextResponse.json({ error: "invalid webhook" }, { status: 400 });
+  }
+}
+
+async function handleDecision(args: {
+  id: string;
+  event: string;
+  data: any;
+  state_snapshot?: Record<string, any>;
+}) {
+  // Example: resume a workflow run or LangGraph thread using `state_snapshot`
 }
 ```
 
+This pattern works similarly for Express/Fastify — call `lp.webhookHandler(rawBody, signature, secret)`, then resume your framework using the provided `state_snapshot`.
+
 ### LangGraph Integration (Persisted State)
 
-LetsPing provides a `LetsPingCheckpointer` for LangGraph JS/TS that automatically encrypts and parks your agent's state in Cryo-Sleep storage.
+LetsPing provides a `LetsPingCheckpointer` for LangGraph JS/TS under `@letsping/sdk/integrations/langgraph`.  
+In v0.2 this checkpointer persists checkpoints **remotely** via the LetsPing control plane — encrypted alongside your existing Cryo‑Sleep state in Supabase Storage. Threads can survive process restarts without you wiring your own database.
 
 ```typescript
 import { StateGraph } from "@langchain/langgraph";
 import { LetsPing } from "@letsping/sdk";
+import { LetsPingCheckpointer } from "@letsping/sdk/integrations/langgraph";
+
+const lp = new LetsPing(process.env.LETSPING_API_KEY!);
+const checkpointer = new LetsPingCheckpointer(lp);
+
+const builder = new StateGraph<any /* your state type */>({});
+const graph = builder.compile({ checkpointer });
+```
 
-// Import the checkpointer from the specific integration path
+#### Auto‑resuming a thread after approval (webhook + checkpointer)
+
+Because checkpoints are stored remotely, you can resume a LangGraph thread from any worker once a human clicks Approve. A minimal Next.js webhook + auto‑resume flow looks like:
+
+```ts
+// Example Next.js App Router route for LangGraph auto-resume
+import { NextRequest, NextResponse } from "next/server";
+import { LetsPing } from "@letsping/sdk";
+import { StateGraph } from "@langchain/langgraph";
 import { LetsPingCheckpointer } from "@letsping/sdk/integrations/langgraph";
+import { graphBuilder } from "@/lib/langgraph"; // your app's graph definition
 
 const lp = new LetsPing(process.env.LETSPING_API_KEY!);
 const checkpointer = new LetsPingCheckpointer(lp);
+const graph = graphBuilder.compile({ checkpointer });
+
+export async function POST(req: NextRequest) {
+  const raw = await req.text();
+  const sig = req.headers.get("x-letsping-signature") || "";
+
+  const event = await lp.webhookHandler(raw, sig, process.env.LETSPING_WEBHOOK_SECRET!);
+  const { data, state_snapshot } = event;
+
+  // You decide how to encode the thread id into your state snapshot.
+  const threadId = state_snapshot?.thread_id as string | undefined;
+  if (!threadId) return NextResponse.json({ ok: false, error: "missing_thread_id" }, { status: 400 });
+
+  // Resume the graph from the latest remote checkpoint.
+  await graph.invoke(state_snapshot.input, {
+    configurable: { thread_id: threadId },
+  });
+
+  return NextResponse.json({ ok: true });
+}
 ```
 
+In your agent runner, you simply include `thread_id` and `state_snapshot` when you first call LetsPing from inside a LangGraph node. The checkpointer and webhook then keep the thread resumable across restarts. If the human edited the payload in the dashboard, `data.patched_payload` (or `data.payload`) is available in the webhook payload — use your framework’s normal state-update or channel overwrite semantics to inject the approved payload into the resumed graph so the run sees the correct values.
+
 ## API Reference
 
 ### `new LetsPing(apiKey, options?)`
@@ -140,7 +241,7 @@ Blocks until resolved (approve / reject / timeout).
 | `payload`    | `Record<string, any>`           | Context passed to human operator (and returned in Decision)                 |
 | `priority`   | `"low" \| "medium" \| "high" \| "critical"` | Routing priority in dashboard                                               |
 | `schema`     | `object`                        | JSON Schema (draft 07) — generates editable form in dashboard               |
-| `timeoutMs`  | `number`                        | Max wait time (default: 86_400_000 ms = 24 hours)                           |
+| `timeoutMs`  | `number`                        | Max wait time in **milliseconds** (default: 86_400_000 ms = 24 hours)      |
 
 ### `lp.defer(options): Promise<{ id: string }>`
 
@@ -150,12 +251,14 @@ Fire-and-forget: queues request and returns request ID immediately. Same options
 
 ```typescript
 interface Decision {
-  status: "APPROVED" | "REJECTED";
+  status: "APPROVED" | "REJECTED" | "APPROVED_WITH_MODIFICATIONS";
   payload: Record<string, any>;          // Original payload sent by agent
   patched_payload?: Record<string, any>; // Human-edited values (if modified)
-  metadata: {
+  diff_summary?: any;                    // Field-level diff between payload and patched_payload
+  metadata?: {
     actor_id: string;                    // ID/email of the approving/rejecting human
     resolved_at: string;                 // ISO 8601 timestamp
+    method?: string;                     // Optional resolution method (e.g. "dashboard")
   };
 }
 ```
@@ -163,4 +266,79 @@ interface Decision {
 For full documentation, request schema examples, error codes, and dashboard integration see:  
 https://letsping.co/docs#sdk
 
-Deploy agents with confidence.
+### Agent-to-Agent Escrow (optional)
+
+For multi-agent systems that want cryptographic guarantees around handoffs, the SDK exposes:
+
+- `signAgentCall(agentId, secret, call)` to attach `agent_id` and `agent_signature` to `/ingest` calls.
+- `signIngestBody(agentId, secret, body)` to take an existing ingest body (`{ project_id, service, action, payload }`) and return it with `agent_id` and `agent_signature` attached.
+- `verifyEscrow(event, secret)` to validate LetsPing escrow webhooks.
+- `chainHandoff(previous, nextData, secret)` to safely construct downstream handoffs tied to the original request id.
+
+See the one-page spec at `/docs/agent-escrow-spec` in the LetsPing web app for the exact wire format and interoperability rules.
+
+Deploy agents with confidence.
+
+## 2-Minute Demo (Node/TypeScript)
+
+You can feel the full LetsPing loop (intercept → approve → resume) in under 2 minutes.
+
+```ts
+// demo.ts
+import { LetsPing } from "@letsping/sdk";
+
+async function main() {
+  const apiKey = process.env.LETSPING_API_KEY;
+  if (!apiKey) {
+    console.error("Missing LETSPING_API_KEY env var.");
+    process.exit(1);
+  }
+
+  const lp = new LetsPing(apiKey);
+
+  console.log("Sending demo approval request to LetsPing…");
+  const decision = await lp.ask({
+    service: "demo-agent",
+    action: "transfer_funds",
+    priority: "high",
+    payload: {
+      amount: 500,
+      currency: "USD",
+      recipient: "acct_demo_123",
+    },
+  });
+
+  if (decision.status === "REJECTED") {
+    console.log("Demo request REJECTED by human. No action taken.");
+  } else if (decision.status === "APPROVED_WITH_MODIFICATIONS") {
+    console.log("APPROVED WITH MODIFICATIONS:");
+    console.dir(decision.diff_summary, { depth: null });
+  } else {
+    console.log("APPROVED with original payload.");
+  }
+}
+
+main().catch((err) => {
+  console.error("Demo failed:", err);
+  process.exit(1);
+});
+```
+
+Run:
+
+```bash
+export LETSPING_API_KEY="lp_live_..."
+node demo.ts
+```
+
+Then open the LetsPing dashboard for your project, approve/reject the `demo-agent / transfer_funds` request, and watch the script resume.
+
+If you’re using the local tunnel (`npx @letsping/cli dev`), you can also point the SDK at it during local development:
+
+```ts
+const lp = new LetsPing(process.env.LETSPING_API_KEY!, {
+  baseUrl: "http://localhost:<port>/api",
+});
+```
+
+All `ask` / `defer` calls made through that client will flow through your local tunnel into the LetsPing dashboard.

package/examples/langgraph-demo.ts

@@ -0,0 +1,80 @@
+import { StateGraph, START } from "@langchain/langgraph";
+import { LetsPing } from "@letsping/sdk";
+import { LetsPingCheckpointer } from "@letsping/sdk/integrations/langgraph";
+
+type DemoState = {
+  thread_id: string;
+  step: "START" | "NEEDS_APPROVAL" | "DONE";
+  amount: number;
+};
+
+const lp = new LetsPing(process.env.LETSPING_API_KEY!);
+const checkpointer = new LetsPingCheckpointer(lp);
+
+// Chain the methods directly off the instantiation
+const builder = new StateGraph<DemoState>({
+  channels: {
+    thread_id: null,
+    step: null,
+    amount: null,
+  },
+})
+  .addNode("charge_step", async (state: DemoState): Promise<DemoState> => {
+    // On the first pass, ask LetsPing for approval and park state.
+    if (state.step === "START") {
+      const decision = await lp.defer({
+        service: "demo-agent",
+        action: "payments:charge",
+        priority: "high",
+        payload: { amount: state.amount },
+        // Persist enough context so the webhook can resume the same thread.
+        state_snapshot: {
+          thread_id: state.thread_id,
+          input: state,
+        },
+      });
+
+      console.log("Queued LetsPing request id:", decision.id);
+
+      return {
+        ...state,
+        step: "NEEDS_APPROVAL",
+      };
+    }
+
+    // After approval + webhook resume, the graph will be invoked again
+    if (state.step === "NEEDS_APPROVAL") {
+      console.log("Approval received. Performing final charge for:", state.amount);
+      return {
+        ...state,
+        step: "DONE",
+      };
+    }
+
+    return state;
+  })
+  // Notice we are chaining addEdge directly after addNode
+  .addEdge(START, "charge_step");
+
+export const demoGraph = builder.compile({ checkpointer });
+
+if (require.main === module) {
+  (async () => {
+    const threadId = `demo-${Date.now()}`;
+    console.log("Starting demo thread:", threadId);
+
+    await demoGraph.invoke(
+      {
+        thread_id: threadId,
+        step: "START",
+        amount: 500,
+      },
+      { configurable: { thread_id: threadId } },
+    );
+
+    console.log("Demo graph invoked. Wait for LetsPing approval, then webhook will resume.");
+  })().catch((e) => {
+    console.error(e);
+    process.exit(1);
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@letsping/sdk",
-  "version": "0.1.6",
+  "version": "0.2.1",
   "description": "Behavioral Firewall and Cryo-Sleep State Parking for Autonomous Agents",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",

package/src/index.d.ts

@@ -8,15 +8,67 @@ export interface RequestOptions {
     timeoutMs?: number;
 }
 export interface Decision {
-    status: "APPROVED" | "REJECTED";
+    status: "APPROVED" | "REJECTED" | "APPROVED_WITH_MODIFICATIONS";
     payload: any;
     patched_payload?: any;
+    diff_summary?: any;
     metadata?: {
         resolved_at: string;
         actor_id: string;
         method?: string;
     };
 }
+export interface EscrowEnvelope {
+    id: string;
+    event: string;
+    data: any;
+    escrow?: {
+        mode: "none" | "handoff" | "finalized";
+        handoff_signature: string | null;
+        upstream_agent_id: string | null;
+        downstream_agent_id: string | null;
+    };
+}
+export declare function verifyEscrow(event: EscrowEnvelope, secret: string): boolean;
+export interface AgentCallPayload {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+}
+export declare function signAgentCall(agentId: string, secret: string, call: AgentCallPayload): {
+    agent_id: string;
+    agent_signature: string;
+};
+export declare function signIngestBody(agentId: string, secret: string, body: {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+}): {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+    agent_id: string;
+    agent_signature: string;
+};
+export declare function verifyAgentSignature(agentId: string, secret: string, call: AgentCallPayload, signature: string): boolean;
+export declare function chainHandoff(previous: EscrowEnvelope, nextData: {
+    service: string;
+    action: string;
+    payload: any;
+    upstream_agent_id: string;
+    downstream_agent_id: string;
+}, secret: string): {
+    payload: any;
+    escrow: {
+        mode: "handoff";
+        upstream_agent_id: string;
+        downstream_agent_id: string;
+        handoff_signature: string;
+    };
+};
 export declare class LetsPingError extends Error {
     status?: number | undefined;
     constructor(message: string, status?: number | undefined);
@@ -26,10 +78,15 @@ export declare class LetsPing {
     private readonly baseUrl;
     constructor(apiKey?: string, options?: {
         baseUrl?: string;
+        encryptionKey?: string;
     });
     ask(options: RequestOptions): Promise<Decision>;
     defer(options: RequestOptions): Promise<{
         id: string;
     }>;
+    waitForDecision(id: string, options?: {
+        originalPayload?: Record<string, any>;
+        timeoutMs?: number;
+    }): Promise<Decision>;
     private request;
 }

package/src/index.ts

@@ -1,6 +1,6 @@
 import { createCipheriv, createDecipheriv, randomBytes, createHmac } from "node:crypto";
 
-let SDK_VERSION = "0.1.6";
+let SDK_VERSION = "0.2.1";
 try {
 
     SDK_VERSION = require("../package.json").version;
@@ -37,6 +37,14 @@ export interface RequestOptions {
     timeoutMs?: number;
 
     role?: string;
+
+    /**
+     * Optional distributed tracing identifiers. If provided, these will be
+     * attached to the request envelope so downstream frameworks can stitch
+     * together multi-agent flows.
+     */
+    trace_id?: string;
+    parent_request_id?: string;
 }
 
 export interface Decision {
@@ -145,6 +153,129 @@ function computeDiff(original: any, patched: any): any {
     return hasChanges ? changes : null;
 }
 
+export interface EscrowEnvelope {
+    id: string;
+    event: string;
+    data: any;
+    escrow?: {
+        mode: "none" | "handoff" | "finalized";
+        handoff_signature: string | null;
+        upstream_agent_id: string | null;
+        downstream_agent_id: string | null;
+    };
+}
+
+export function verifyEscrow(event: EscrowEnvelope, secret: string): boolean {
+    if (!event.escrow || !event.escrow.handoff_signature) return false;
+    const base = {
+        id: event.id,
+        event: event.event,
+        data: event.data,
+        upstream_agent_id: event.escrow.upstream_agent_id,
+        downstream_agent_id: event.escrow.downstream_agent_id,
+    };
+    const expected = createHmac("sha256", secret).update(JSON.stringify(base)).digest("hex");
+    return expected === event.escrow.handoff_signature;
+}
+
+export interface AgentCallPayload {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+}
+
+export function signAgentCall(agentId: string, secret: string, call: AgentCallPayload): {
+    agent_id: string;
+    agent_signature: string;
+} {
+    const canonical = JSON.stringify({
+        project_id: call.project_id,
+        service: call.service,
+        action: call.action,
+        payload: call.payload,
+    });
+    const signature = createHmac("sha256", secret).update(canonical).digest("hex");
+    return {
+        agent_id: agentId,
+        agent_signature: signature,
+    };
+}
+
+export function signIngestBody(
+    agentId: string,
+    secret: string,
+    body: {
+        project_id: string;
+        service: string;
+        action: string;
+        payload: any;
+    }
+): {
+    project_id: string;
+    service: string;
+    action: string;
+    payload: any;
+    agent_id: string;
+    agent_signature: string;
+} {
+    const { agent_id, agent_signature } = signAgentCall(agentId, secret, {
+        project_id: body.project_id,
+        service: body.service,
+        action: body.action,
+        payload: body.payload,
+    });
+    return {
+        ...body,
+        agent_id,
+        agent_signature,
+    };
+}
+
+export function verifyAgentSignature(
+    agentId: string,
+    secret: string,
+    call: AgentCallPayload,
+    signature: string
+): boolean {
+    const { agent_signature } = signAgentCall(agentId, secret, call);
+    return agent_signature === signature;
+}
+
+export function chainHandoff(previous: EscrowEnvelope, nextData: {
+    service: string;
+    action: string;
+    payload: any;
+    upstream_agent_id: string;
+    downstream_agent_id: string;
+}, secret: string): {
+    payload: any;
+    escrow: {
+        mode: "handoff";
+        upstream_agent_id: string;
+        downstream_agent_id: string;
+        handoff_signature: string;
+    };
+} {
+    const base = {
+        id: previous.id,
+        event: previous.event,
+        data: nextData.payload,
+        upstream_agent_id: nextData.upstream_agent_id,
+        downstream_agent_id: nextData.downstream_agent_id,
+    };
+    const handoff_signature = createHmac("sha256", secret).update(JSON.stringify(base)).digest("hex");
+    return {
+        payload: nextData.payload,
+        escrow: {
+            mode: "handoff",
+            upstream_agent_id: nextData.upstream_agent_id,
+            downstream_agent_id: nextData.downstream_agent_id,
+            handoff_signature,
+        },
+    };
+}
+
 export class LetsPing {
     private readonly apiKey: string;
     private readonly baseUrl: string;
@@ -222,14 +353,30 @@ export class LetsPing {
             });
         }
 
+        const traceId = options.trace_id;
+        const parentId = options.parent_request_id;
+
+        // Do not mutate caller payload; attach tracing metadata under a reserved key.
+        const basePayload = options.payload || {};
+        const metaKey = "_lp_meta";
+        const existingMeta = (basePayload as any)[metaKey] || {};
+        const enrichedPayload = {
+            ...basePayload,
+            [metaKey]: {
+                ...existingMeta,
+                ...(traceId ? { trace_id: traceId } : {}),
+                ...(parentId ? { parent_request_id: parentId } : {}),
+            },
+        };
+
         try {
             const res = await this.request<{ id: string, uploadUrl?: string, dek?: string }>("POST", "/ingest", {
                 service: options.service,
                 action: options.action,
-                payload: this._encrypt(options.payload),
+                payload: this._encrypt(enrichedPayload),
                 priority: options.priority || "medium",
                 schema: options.schema,
-                metadata: { role: options.role, sdk: "node" }
+                metadata: { role: options.role, sdk: "node", trace_id: traceId, parent_request_id: parentId }
             });
 
             const { id, uploadUrl, dek } = res;
@@ -325,10 +472,28 @@ export class LetsPing {
             });
         }
 
+        const traceId = options.trace_id;
+        const parentId = options.parent_request_id;
+        const basePayload = options.payload || {};
+        const metaKey = "_lp_meta";
+        const existingMeta = (basePayload as any)[metaKey] || {};
+        const enrichedPayload = {
+            ...basePayload,
+            [metaKey]: {
+                ...existingMeta,
+                ...(traceId ? { trace_id: traceId } : {}),
+                ...(parentId ? { parent_request_id: parentId } : {}),
+            },
+        };
+
         try {
             const res = await this.request<{ id: string, uploadUrl?: string, dek?: string }>("POST", "/ingest", {
-                ...options,
-                payload: this._encrypt(options.payload),
+                service: options.service,
+                action: options.action,
+                payload: this._encrypt(enrichedPayload),
+                priority: options.priority || "medium",
+                schema: options.schema,
+                metadata: { role: options.role, sdk: "node", trace_id: traceId, parent_request_id: parentId },
             });
             if (res.uploadUrl && options.state_snapshot) {
                 try {
@@ -392,6 +557,56 @@ export class LetsPing {
         }
     }
 
+    async waitForDecision(
+        id: string,
+        options?: { originalPayload?: Record<string, any>; timeoutMs?: number }
+    ): Promise<Decision> {
+        const basePayload = options?.originalPayload || {};
+        const timeout = options?.timeoutMs || 24 * 60 * 60 * 1000;
+        const start = Date.now();
+        let delay = 1000;
+        const maxDelay = 10000;
+
+        while (Date.now() - start < timeout) {
+            try {
+                const check = await this.request<any>("GET", `/status/${id}`);
+
+                if (check.status === "APPROVED" || check.status === "REJECTED") {
+                    const decryptedPayload = this._decrypt(check.payload) ?? basePayload;
+                    const decryptedPatched = check.patched_payload ? this._decrypt(check.patched_payload) : undefined;
+
+                    let diff_summary;
+                    let finalStatus: Decision["status"] = check.status;
+                    if (check.status === "APPROVED" && decryptedPatched !== undefined) {
+                        finalStatus = "APPROVED_WITH_MODIFICATIONS";
+                        const diff = computeDiff(decryptedPayload, decryptedPatched);
+                        diff_summary = diff ? { changes: diff } : { changes: "Unknown structure changes" };
+                    }
+
+                    return {
+                        status: finalStatus,
+                        payload: decryptedPayload,
+                        patched_payload: decryptedPatched,
+                        diff_summary,
+                        metadata: {
+                            resolved_at: check.resolved_at,
+                            actor_id: check.actor_id,
+                        }
+                    };
+                }
+            } catch (e: any) {
+                const s = e.status;
+                if (s && s >= 400 && s < 500 && s !== 404 && s !== 429) throw e;
+            }
+
+            const jitter = Math.random() * 200;
+            await new Promise(r => setTimeout(r, delay + jitter));
+            delay = Math.min(delay * 1.5, maxDelay);
+        }
+
+        throw new LetsPingError(`Request ${id} timed out waiting for approval.`);
+    }
+
     tool(service: string, action: string, priority: Priority = "medium"): (context: string | Record<string, any>) => Promise<string> {
         return async (context: string | Record<string, any>): Promise<string> => {
             let payload: Record<string, any>;
@@ -436,11 +651,29 @@ export class LetsPing {
         signatureHeader: string,
         webhookSecret: string
     ): Promise<{ id: string; event: string; data: Decision; state_snapshot?: Record<string, any> }> {
-        const hmac = createHmac("sha256", webhookSecret).update(payloadStr).digest("hex");
         const sigParts = signatureHeader.split(",").map(p => p.split("="));
         const sigMap = Object.fromEntries(sigParts);
 
-        if (sigMap["v1"] !== hmac) {
+        const rawTs = sigMap["t"];
+        const rawSig = sigMap["v1"];
+        if (!rawTs || !rawSig) {
+            throw new LetsPingError("LetsPing Error: Missing webhook signature fields", 401);
+        }
+
+        const ts = Number(rawTs);
+        if (!Number.isFinite(ts)) {
+            throw new LetsPingError("LetsPing Error: Invalid webhook timestamp", 401);
+        }
+
+        const now = Date.now();
+        const skewMs = Math.abs(now - ts);
+        const maxSkewMs = 5 * 60 * 1000; // 5 minutes
+        if (skewMs > maxSkewMs) {
+            throw new LetsPingError("LetsPing Error: Webhook replay window exceeded", 401);
+        }
+
+        const expected = createHmac("sha256", webhookSecret).update(payloadStr).digest("hex");
+        if (rawSig !== expected) {
             throw new LetsPingError("LetsPing Error: Invalid webhook signature", 401);
         }
 

package/src/integrations/langgraph.ts

@@ -2,13 +2,84 @@ import { BaseCheckpointSaver, Checkpoint, CheckpointMetadata, CheckpointTuple }
 import { RunnableConfig } from "@langchain/core/runnables";
 import { LetsPing } from "../index";
 
+type StoredCheckpoint = {
+    checkpoint: Checkpoint;
+    metadata: CheckpointMetadata;
+};
+
 export class LetsPingCheckpointer extends BaseCheckpointSaver {
-    private checkpoints: Record<string, [Checkpoint, CheckpointMetadata]> = {};
+    private checkpoints: Record<string, StoredCheckpoint> = {};
 
     constructor(public client: LetsPing) {
         super();
     }
 
+    private getTransport(): (<T = any>(method: string, path: string, body?: any) => Promise<T>) | null {
+        const clientAny = this.client as any;
+        if (typeof clientAny.request === "function") {
+            return clientAny.request.bind(this.client);
+        }
+        return null;
+    }
+
+    private async saveRemote(
+        threadId: string,
+        checkpointId: string,
+        checkpoint: Checkpoint,
+        metadata: CheckpointMetadata
+    ): Promise<void> {
+        const transport = this.getTransport();
+        if (!transport) {
+            console.warn("[LetsPingCheckpointer] Missing underlying transport; falling back to in-memory only.");
+            return;
+        }
+        try {
+            await transport("POST", "/langgraph/checkpoints", {
+                thread_id: threadId,
+                checkpoint_id: checkpointId,
+                checkpoint,
+                metadata,
+            });
+        } catch (e) {
+            console.warn("[LetsPingCheckpointer] Failed to persist checkpoint remotely; falling back to in-memory only.", e);
+        }
+    }
+
+    private async loadRemote(
+        threadId: string,
+        checkpointId?: string
+    ): Promise<StoredCheckpoint | null> {
+        const transport = this.getTransport();
+        if (!transport) {
+            console.warn("[LetsPingCheckpointer] Missing underlying transport; using in-memory checkpoints only.");
+            return null;
+        }
+        const search = checkpointId
+            ? `?thread_id=${encodeURIComponent(threadId)}&checkpoint_id=${encodeURIComponent(checkpointId)}`
+            : `?thread_id=${encodeURIComponent(threadId)}&latest=1`;
+        try {
+            const res = await transport<any>("GET", `/langgraph/checkpoints${search}`);
+            if (res && res.checkpoint && res.metadata) {
+                return { checkpoint: res.checkpoint as Checkpoint, metadata: res.metadata as CheckpointMetadata };
+            }
+        } catch (e) {
+            // If not found or backend unavailable, fall back to local cache only.
+            console.warn("[LetsPingCheckpointer] Failed to load remote checkpoint", e);
+        }
+        return null;
+    }
+
+    private async deleteRemote(threadId: string): Promise<void> {
+        const transport = this.getTransport();
+        if (!transport) return;
+        const search = `?thread_id=${encodeURIComponent(threadId)}`;
+        try {
+            await transport("DELETE", `/langgraph/checkpoints${search}`);
+        } catch (e) {
+            console.warn("[LetsPingCheckpointer] Failed to delete remote checkpoints", e);
+        }
+    }
+
     async put(
         config: RunnableConfig,
         checkpoint: Checkpoint,
@@ -18,17 +89,22 @@ export class LetsPingCheckpointer extends BaseCheckpointSaver {
         const threadId = config.configurable?.thread_id;
         const checkpointId = checkpoint.id;
 
-        this.checkpoints[`${threadId}:${checkpointId}`] = [checkpoint, metadata];
+        if (!threadId || !checkpointId) {
+            return config;
+        }
+
+        this.checkpoints[`${threadId}:${checkpointId}`] = { checkpoint, metadata };
+        await this.saveRemote(threadId, checkpointId, checkpoint, metadata);
 
         return {
             configurable: {
                 thread_id: threadId,
                 checkpoint_id: checkpointId,
-            }
+            },
         };
     }
 
-    // --- NEW METHODS REQUIRED BY LANGGRAPH V0.1+ ---
+    // METHODS REQUIRED BY LANGGRAPH V0.1+
     async putWrites(config: RunnableConfig, writes: any, taskId: string): Promise<void> {
         // No-op for V1: LetsPing focuses on primary state parking, not granular sub-task writes.
     }
@@ -39,27 +115,49 @@ export class LetsPingCheckpointer extends BaseCheckpointSaver {
                 delete this.checkpoints[key];
             }
         }
+        await this.deleteRemote(threadId);
     }
 
     async getTuple(config: RunnableConfig): Promise<CheckpointTuple | undefined> {
         const threadId = config.configurable?.thread_id;
         const checkpointId = config.configurable?.checkpoint_id;
+        if (!threadId) return undefined;
+
+        // Prefer remote truth, fall back to local cache.
+        const remote = await this.loadRemote(threadId, checkpointId);
+        if (remote) {
+            return { config, checkpoint: remote.checkpoint, metadata: remote.metadata };
+        }
 
         if (checkpointId) {
             const match = this.checkpoints[`${threadId}:${checkpointId}`];
-            if (match) return { config, checkpoint: match[0], metadata: match[1] };
+            if (match) {
+                return { config, checkpoint: match.checkpoint, metadata: match.metadata };
+            }
         }
 
         let latest: CheckpointTuple | undefined;
         for (const [key, val] of Object.entries(this.checkpoints)) {
             if (key.startsWith(`${threadId}:`)) {
-                latest = { config, checkpoint: val[0], metadata: val[1] };
+                latest = { config, checkpoint: val.checkpoint, metadata: val.metadata };
             }
         }
         return latest;
     }
 
     async *list(config: RunnableConfig, options?: any): AsyncGenerator<CheckpointTuple> {
-        yield* [];
+        const threadId = config.configurable?.thread_id;
+        if (!threadId) return;
+
+        const remoteLatest = await this.loadRemote(threadId);
+        if (remoteLatest) {
+            yield { config, checkpoint: remoteLatest.checkpoint, metadata: remoteLatest.metadata };
+        }
+
+        for (const [key, val] of Object.entries(this.checkpoints)) {
+            if (key.startsWith(`${threadId}:`)) {
+                yield { config, checkpoint: val.checkpoint, metadata: val.metadata };
+            }
+        }
     }
 }