managed-deepagents 0.0.3-dev.46 → 0.0.3-dev.47

package/dist/runtime/langsmith-connector.js

@@ -18,6 +18,10 @@ import { Client } from "langsmith";
 /** An error carrying an HTTP status the engine surfaces to the caller. */
 export class EnforcementError extends Error {
     status;
+    /**
+     * @param status - HTTP status code returned to the caller.
+     * @param message - Human-readable error detail.
+     */
     constructor(status, message) {
         super(message);
         this.status = status;
@@ -28,6 +32,10 @@ export class EnforcementError extends Error {
  * Mount the capability route on the connector's namespaced sub-router. Runs the
  * identity-dependent authoring checks at mount time (fails startup on an illegal
  * scope/ingress combination), then registers the uniform POST endpoint.
+ *
+ * @param ctx - HTTP mount context with the namespaced router and identity config.
+ * @param capabilities - Declared LangSmith capabilities to expose.
+ * @param client - LangSmith client used for server-side operations; defaults to {@link defaultClient}.
  */
 export function mountLangSmithRoutes(ctx, capabilities, client = defaultClient()) {
     validateAgainstIdentity(capabilities, ctx.identity);
@@ -41,7 +49,14 @@ export function mountLangSmithRoutes(ctx, capabilities, client = defaultClient()
     // second argument.
     ctx.router.post("/capabilities/:id", (request, identity) => handleCapabilityRequest(request, identity, deps));
 }
-/** Identity-aware authoring validation, run when the app is constructed. */
+/**
+ * Identity-aware authoring validation, run when the app is constructed.
+ * Rejects illegal scope/ingress combinations before any request is served.
+ *
+ * @param capabilities - Declared LangSmith capabilities to validate.
+ * @param identity - Deployment identity config, or `undefined` when identity is not configured.
+ * @throws {Error} When a capability's scope, exposure, or tenancy is illegal for this deployment.
+ */
 export function validateAgainstIdentity(capabilities, identity) {
     const httpMode = identity?.ingress.http;
     const hasValidatedToken = httpMode !== undefined && httpMode !== "trusted_backend";
@@ -74,7 +89,16 @@ export function validateAgainstIdentity(capabilities, identity) {
         }
     }
 }
-/** The per-request enforcement pipeline. Returns a JSON `Response`. */
+/**
+ * Per-request enforcement pipeline for a capability POST.
+ * Resolves the capability, checks surface/action, proves thread ownership when
+ * needed, enforces scope, performs the LangSmith call, and shapes the response.
+ *
+ * @param request - Incoming HTTP request for `/capabilities/:id`.
+ * @param identity - Frozen runtime identity resolved by the secure router.
+ * @param deps - Closed-over capabilities map, LangSmith client, and optional access prover.
+ * @returns JSON `Response` with `{ data }` on success or `{ error }` on failure.
+ */
 export async function handleCapabilityRequest(request, identity, deps) {
     try {
         const capabilityId = capabilityIdFromUrl(request.url);
@@ -91,9 +115,15 @@ export async function handleCapabilityRequest(request, identity, deps) {
         if (!capability.actions.includes(action)) {
             throw new EnforcementError(403, `action "${action}" is not allowed for capability "${capability.id}"`);
         }
-        // Connector HTTP has no LangGraph configurable.thread_id; browser callers
-        // supply thread context in the body so thread/run scopes can bind.
-        const scopedIdentity = bindIdentityThread(identity, body);
+        // Connector HTTP has no LangGraph configurable.thread_id. Resolve a thread
+        // id from identity / run / body, prove access when it is client-supplied,
+        // then bind the proven id onto identity for the rest of the request.
+        const assertThreadAccess = deps.assertThreadAccess ??
+            defaultAssertThreadAccess(request, identity, deps.identityConfig);
+        const provenThreadId = await resolveProvenThreadId(capability, identity, body, deps.client, assertThreadAccess);
+        const scopedIdentity = provenThreadId
+            ? withIdentityThread(identity, provenThreadId)
+            : identity;
         await assertCapabilityScope(capability, scopedIdentity, body, deps.client);
         const raw = toRecord(await performLangSmithCall(capability, action, body, deps, scopedIdentity));
         const shaped = shapeResponse(raw, capability);
@@ -107,7 +137,13 @@ export async function handleCapabilityRequest(request, identity, deps) {
         return jsonResponse(status, { error: errorMessage(error) });
     }
 }
-/** Map the resolved identity + ingress mode to a caller surface. */
+/**
+ * Map the resolved identity + ingress mode to a caller surface.
+ *
+ * @param identity - Frozen runtime identity for this request.
+ * @param identityConfig - Deployment identity config (ingress mode).
+ * @returns The surface used for `exposeTo` checks (`browser`, `trusted_backend`, `channel`, or `schedule`).
+ */
 export function callerSurface(identity, identityConfig) {
     const provider = identity.source.provider;
     if (provider === "slack") {
@@ -122,7 +158,12 @@ export function callerSurface(identity, identityConfig) {
         : "browser";
 }
 // --- Ownership + constraints -----------------------------------------------
-/** Thread id on the frozen identity envelope (`source.threadId`). */
+/**
+ * Read the thread id from the frozen identity envelope (`source.threadId`).
+ *
+ * @param identity - Frozen runtime identity.
+ * @returns Non-empty thread id, or `undefined` when absent.
+ */
 function identityThreadId(identity) {
     const threadId = identity.source.threadId;
     return typeof threadId === "string" && threadId.length > 0
@@ -130,29 +171,192 @@ function identityThreadId(identity) {
         : undefined;
 }
 /**
- * Bind a request-body thread id onto identity when the envelope has none.
+ * Attach a proven thread id onto a copy of the identity envelope.
+ * Returns the same object when the identity already carries that thread id.
  *
- * Agent runs already carry `configurable.thread_id` → `source.threadId`.
- * Browser connector calls do not; callers must pass `threadId`/`thread_id` in
- * the body so thread/run-scoped capabilities can prove ownership.
+ * @param identity - Frozen runtime identity to copy.
+ * @param threadId - Proven thread id to bind onto `source.threadId`.
+ * @returns Identity with `source.threadId` set to `threadId`.
  */
-export function bindIdentityThread(identity, body) {
-    const fromIdentity = identityThreadId(identity);
-    const fromBody = optionalBodyString(body, "threadId", "thread_id");
-    if (fromIdentity && fromBody && fromIdentity !== fromBody) {
-        throw new EnforcementError(403, "body thread id does not match identity thread");
-    }
-    if (fromIdentity || !fromBody) {
+export function withIdentityThread(identity, threadId) {
+    if (identityThreadId(identity) === threadId) {
         return identity;
     }
     return {
         ...identity,
-        source: { ...identity.source, threadId: fromBody },
+        source: { ...identity.source, threadId },
+    };
+}
+/**
+ * Resolve the thread id for a thread/run-scoped capability and prove access
+ * when it did not come from the trusted identity envelope.
+ *
+ * - identity `source.threadId` (server-derived from agent runs) is trusted
+ * - LangSmith run session/thread (when `run_id` is present) is authoritative
+ * - bare body `threadId`/`thread_id` (no identity thread, no run) requires
+ *   {@link AssertThreadAccess}
+ *
+ * @param capability - Capability whose `scope` drives whether a thread id is required.
+ * @param identity - Frozen runtime identity for this request.
+ * @param body - Parsed JSON request body.
+ * @param client - LangSmith client used to load a run when `run_id` is present.
+ * @param assertThreadAccess - Ownership prover for bare body thread ids.
+ * @returns Proven thread id, or the identity thread id for non-thread/run scopes.
+ * @throws {EnforcementError} On missing/mismatched thread ids or failed ownership proof.
+ */
+export async function resolveProvenThreadId(capability, identity, body, client, assertThreadAccess) {
+    if (capability.scope !== "thread" && capability.scope !== "run") {
+        return identityThreadId(identity);
+    }
+    const fromIdentity = identityThreadId(identity);
+    const fromBody = optionalBodyString(body, "threadId", "thread_id");
+    const runId = optionalBodyString(body, "runId", "run_id");
+    let fromRun;
+    if (runId) {
+        const run = toRecord(await client.readRun({ runId }));
+        fromRun = runThreadId(run);
+        if (!fromRun) {
+            throw new EnforcementError(403, "run has no thread id");
+        }
+    }
+    else if (capability.scope === "run") {
+        // update/delete may omit runId; require identity or body thread below
+    }
+    for (const [left, right, label] of [
+        [fromIdentity, fromBody, "body thread id does not match identity thread"],
+        [fromIdentity, fromRun, "run does not belong to identity thread"],
+        [fromBody, fromRun, "body thread id does not match run thread"],
+    ]) {
+        if (left && right && left !== right) {
+            throw new EnforcementError(403, label);
+        }
+    }
+    const threadId = fromIdentity ?? fromRun ?? fromBody;
+    if (!threadId) {
+        throw new EnforcementError(403, `${capability.scope} scope requires thread id (identity source, run, or request body)`);
+    }
+    // Identity- and run-derived thread ids are already proven. Only a bare body
+    // thread id (no identity thread, no run) needs a live ownership check.
+    if (!fromIdentity && !fromRun) {
+        await assertThreadAccess(threadId);
+    }
+    return threadId;
+}
+/**
+ * Build the default ownership proof: `GET /threads/{id}` with the caller's
+ * credentials and require `metadata.owner` to match the identity's thread-owner key.
+ *
+ * @param request - Incoming request whose auth headers are forwarded to the thread GET.
+ * @param identity - Frozen runtime identity used to derive the expected owner key.
+ * @param identityConfig - Deployment identity config (`scoping.threads`).
+ * @returns An `AssertThreadAccess` function closed over the request and expected owner.
+ */
+export function defaultAssertThreadAccess(request, identity, identityConfig) {
+    const expectedOwner = threadOwnerFromIdentity(identity, identityConfig);
+    return async (threadId) => {
+        if (!expectedOwner) {
+            throw new EnforcementError(403, "thread access requires identity.actor.id");
+        }
+        const threadUrl = new URL(request.url);
+        threadUrl.pathname = `/threads/${encodeURIComponent(threadId)}`;
+        threadUrl.search = "";
+        const headers = forwardAuthHeaders(request);
+        let response;
+        try {
+            response = await fetch(threadUrl, { method: "GET", headers });
+        }
+        catch {
+            throw new EnforcementError(502, "failed to verify thread access");
+        }
+        if (response.status === 401) {
+            throw new EnforcementError(401, "unauthorized");
+        }
+        if (response.status === 403 || response.status === 404) {
+            throw new EnforcementError(403, "thread is not accessible to this identity");
+        }
+        if (!response.ok) {
+            throw new EnforcementError(502, `failed to verify thread access (${response.status})`);
+        }
+        let payload;
+        try {
+            payload = await response.json();
+        }
+        catch {
+            return;
+        }
+        const owner = threadOwnerFromPayload(payload);
+        if (owner && owner !== expectedOwner) {
+            throw new EnforcementError(403, "thread is not accessible to this identity");
+        }
     };
 }
+/**
+ * Owner key used by `@auth.on.threads` for this identity.
+ *
+ * @param identity - Frozen runtime identity.
+ * @param identityConfig - Deployment identity config (`scoping.threads`).
+ * @returns Actor or tenant id used as the thread `metadata.owner`, or `undefined` when missing.
+ */
+function threadOwnerFromIdentity(identity, identityConfig) {
+    const scope = identityConfig?.scoping?.threads ?? "actor";
+    if (scope === "tenant") {
+        return identity.tenant?.id ?? identity.actor?.id;
+    }
+    return identity.actor?.id;
+}
+/**
+ * Extract `metadata.owner` from a LangGraph thread payload.
+ *
+ * @param payload - Parsed JSON body from `GET /threads/{id}`.
+ * @returns Non-empty owner string, or `undefined` when absent/malformed.
+ */
+function threadOwnerFromPayload(payload) {
+    if (!payload || typeof payload !== "object" || Array.isArray(payload)) {
+        return undefined;
+    }
+    const metadata = payload.metadata;
+    if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)) {
+        return undefined;
+    }
+    const owner = metadata.owner;
+    return typeof owner === "string" && owner.length > 0 ? owner : undefined;
+}
+const FORWARDED_AUTH_HEADERS = [
+    "authorization",
+    "cookie",
+    "x-api-key",
+    "x-auth-key",
+    "x-supabase-region",
+    "x-mda-ingress-secret",
+    "x-mda-actor-id",
+    "x-mda-tenant-id",
+];
+/**
+ * Copy auth-related headers from the inbound request for same-origin thread GETs.
+ *
+ * @param request - Incoming capability request.
+ * @returns Headers containing only the allowlisted auth fields that were present.
+ */
+function forwardAuthHeaders(request) {
+    const headers = new Headers();
+    for (const name of FORWARDED_AUTH_HEADERS) {
+        const value = request.headers.get(name);
+        if (value) {
+            headers.set(name, value);
+        }
+    }
+    return headers;
+}
 /**
  * Prove the capability's ownership scope from `runtime.identity` before the
- * LangSmith call.
+ * LangSmith call. Thread id must already be present on identity when required
+ * (see {@link resolveProvenThreadId}).
+ *
+ * @param capability - Capability whose `scope` is enforced.
+ * @param identity - Identity with any proven thread id already bound.
+ * @param body - Parsed JSON request body (used for run-scoped `run_id` checks).
+ * @param client - LangSmith client used to load runs for run-scope verification.
+ * @throws {EnforcementError} When the identity lacks the required scope fields or the run is foreign.
  */
 export async function assertCapabilityScope(capability, identity, body, client) {
     switch (capability.scope) {
@@ -173,18 +377,20 @@ export async function assertCapabilityScope(capability, identity, body, client)
             return;
         }
         case "thread": {
-            const threadId = identityThreadId(identity);
-            if (!threadId) {
-                throw new EnforcementError(403, "thread scope requires thread id (identity source or request body)");
+            if (!identityThreadId(identity)) {
+                throw new EnforcementError(403, "thread scope requires thread id (identity source, run, or request body)");
             }
             return;
         }
         case "run": {
             const threadId = identityThreadId(identity);
             if (!threadId) {
-                throw new EnforcementError(403, "run scope requires thread id (identity source or request body)");
+                throw new EnforcementError(403, "run scope requires thread id (identity source, run, or request body)");
+            }
+            const runId = await resolveRunIdForScope(body, client);
+            if (!runId) {
+                throw new EnforcementError(403, "run scope requires run id or feedback id");
             }
-            const runId = bodyString(body, "runId", "run_id");
             const run = toRecord(await client.readRun({ runId }));
             const runThread = runThreadId(run);
             if (!runThread || runThread !== threadId) {
@@ -196,25 +402,43 @@ export async function assertCapabilityScope(capability, identity, body, client)
             throw new EnforcementError(400, `unknown capability scope "${String(capability.scope)}"`);
     }
 }
-/** Resolve a run's thread/session id from known LangSmith field locations. */
+/**
+ * Resolve a LangGraph thread id from a LangSmith run.
+ *
+ * Prefer explicit `thread_id` fields. Metadata may also carry `session_id` as
+ * the conversation/thread id. Do **not** use the run's top-level `session_id`:
+ * on LangSmith that field is the tracing project/session UUID, not the
+ * LangGraph thread.
+ *
+ * @param run - LangSmith run record (top-level and metadata bags).
+ * @returns First non-empty LangGraph thread id found, or `undefined`.
+ */
 function runThreadId(run) {
-    const keys = ["session_id", "sessionId", "thread_id", "threadId"];
-    for (const key of keys) {
+    const threadKeys = ["thread_id", "threadId"];
+    const metadataKeys = [
+        "thread_id",
+        "threadId",
+        "session_id",
+        "sessionId",
+    ];
+    for (const key of threadKeys) {
         const value = run[key];
         if (typeof value === "string" && value.length > 0) {
             return value;
         }
     }
+    const metadataBags = [run.metadata];
     const extra = run.extra;
     if (extra && typeof extra === "object" && !Array.isArray(extra)) {
         const extraRecord = extra;
-        const metadata = extraRecord.metadata &&
-            typeof extraRecord.metadata === "object" &&
-            !Array.isArray(extraRecord.metadata)
-            ? extraRecord.metadata
-            : extraRecord;
-        for (const key of keys) {
-            const value = metadata[key];
+        metadataBags.push(extraRecord.metadata ?? extraRecord);
+    }
+    for (const bag of metadataBags) {
+        if (!bag || typeof bag !== "object" || Array.isArray(bag))
+            continue;
+        const record = bag;
+        for (const key of metadataKeys) {
+            const value = record[key];
             if (typeof value === "string" && value.length > 0) {
                 return value;
             }
@@ -222,6 +446,34 @@ function runThreadId(run) {
     }
     return undefined;
 }
+/**
+ * Resolve the run id for run-scoped ownership checks.
+ * Prefer an explicit body `runId`/`run_id`; otherwise load the feedback and
+ * use its `run_id` so update/delete cannot skip thread ownership.
+ *
+ * @param body - Parsed JSON request body.
+ * @param client - LangSmith client used to load feedback when needed.
+ * @returns Run id to verify against the identity thread, or `undefined`.
+ */
+async function resolveRunIdForScope(body, client) {
+    const fromBody = optionalBodyString(body, "runId", "run_id");
+    if (fromBody) {
+        return fromBody;
+    }
+    const feedbackId = optionalBodyString(body, "feedbackId", "feedback_id");
+    if (!feedbackId) {
+        return undefined;
+    }
+    const feedback = toRecord(await client.readFeedback({ feedbackId }));
+    const runId = feedback.run_id ?? feedback.runId;
+    return typeof runId === "string" && runId.length > 0 ? runId : undefined;
+}
+/**
+ * Read the MDA actor id stamped onto feedback metadata (`mda_actor_id`).
+ *
+ * @param feedback - LangSmith feedback record.
+ * @returns Actor id from top-level or `feedback_source` metadata, or `undefined`.
+ */
 function feedbackActorId(feedback) {
     const direct = feedback.metadata;
     if (direct && typeof direct === "object" && !Array.isArray(direct)) {
@@ -242,6 +494,12 @@ function feedbackActorId(feedback) {
     }
     return undefined;
 }
+/**
+ * Read the MDA thread id stamped onto example metadata (`mda_thread_id`).
+ *
+ * @param example - LangSmith example record.
+ * @returns Thread id from `metadata.mda_thread_id`, or `undefined`.
+ */
 function exampleThreadId(example) {
     const metadata = example.metadata;
     if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
@@ -252,7 +510,17 @@ function exampleThreadId(example) {
     }
     return undefined;
 }
-// --- Call mapping ----------------------------------------------------------
+/**
+ * Dispatch a capability action to the matching LangSmith resource handler.
+ *
+ * @param capability - Capability declaring the resource and constraints.
+ * @param action - Requested action name from the body.
+ * @param body - Parsed JSON request body.
+ * @param deps - Handler dependencies including the LangSmith client.
+ * @param identity - Scoped identity (with proven thread id when applicable).
+ * @returns Raw LangSmith SDK result before response shaping.
+ * @throws {EnforcementError} When the resource is unsupported or the action fails validation.
+ */
 async function performLangSmithCall(capability, action, body, deps, identity) {
     switch (capability.resource) {
         case "feedback":
@@ -271,6 +539,18 @@ async function performLangSmithCall(capability, action, body, deps, identity) {
             throw new EnforcementError(400, `resource "${capability.resource}" is not supported in v0`);
     }
 }
+/**
+ * Execute a feedback create/update/delete against LangSmith, applying
+ * capability constraints (`keys`, `scores`, `maxCommentChars`, `onePerActor`).
+ *
+ * @param capability - Feedback capability with constraints.
+ * @param action - One of `create`, `update`, or `delete`.
+ * @param body - Parsed JSON request body.
+ * @param client - LangSmith client.
+ * @param identity - Runtime identity (actor id for `onePerActor` and metadata).
+ * @returns Created feedback, or `void` for update/delete.
+ * @throws {EnforcementError} On invalid action, constraint violation, or duplicate actor feedback.
+ */
 async function feedbackCall(capability, action, body, client, identity) {
     const c = capability.constraints ?? {};
     if (action === "create") {
@@ -325,6 +605,15 @@ async function feedbackCall(capability, action, body, client, identity) {
     }
     throw new EnforcementError(400, `unknown feedback action "${action}"`);
 }
+/**
+ * Execute a runs read or share against LangSmith.
+ *
+ * @param action - One of `read` or `share`.
+ * @param body - Parsed JSON request body (`runId` / `run_id`).
+ * @param client - LangSmith client.
+ * @returns Run record or share URL payload.
+ * @throws {EnforcementError} On unknown action or missing run id.
+ */
 async function runsCall(action, body, client) {
     const runId = bodyString(body, "runId", "run_id");
     if (action === "read") {
@@ -335,6 +624,17 @@ async function runsCall(action, body, client) {
     }
     throw new EnforcementError(400, `unknown runs action "${action}"`);
 }
+/**
+ * Create a LangSmith example in the capability's dataset, applying field and
+ * per-thread caps and stamping MDA metadata.
+ *
+ * @param capability - Examples capability with `dataset` and related constraints.
+ * @param body - Parsed JSON request body (`inputs`, optional `outputs`).
+ * @param client - LangSmith client.
+ * @param identity - Runtime identity (thread/actor metadata and `maxExamplesPerThread`).
+ * @returns Created example.
+ * @throws {EnforcementError} On missing dataset, disallowed fields, or thread example cap.
+ */
 async function examplesCall(capability, body, client, identity) {
     const c = capability.constraints ?? {};
     const dataset = c.dataset;
@@ -383,6 +683,15 @@ async function examplesCall(capability, body, client, identity) {
         ...(Object.keys(metadata).length > 0 ? { metadata } : {}),
     });
 }
+/**
+ * Enqueue a run onto the capability's annotation queue.
+ *
+ * @param capability - Annotation-queue capability with `queue` and related constraints.
+ * @param body - Parsed JSON request body (`runId`, optional `priority` / `note`).
+ * @param client - LangSmith client.
+ * @returns Resolves when the run is enqueued.
+ * @throws {EnforcementError} On missing queue or disallowed priority/note.
+ */
 async function annotationQueueCall(capability, body, client) {
     const c = capability.constraints ?? {};
     const queue = c.queue;
@@ -401,6 +710,16 @@ async function annotationQueueCall(capability, body, client) {
         ...(note !== undefined ? { note } : {}),
     });
 }
+/**
+ * Execute a threads read or metadata update against LangSmith.
+ *
+ * @param capability - Threads capability with metadata constraints.
+ * @param action - One of `read` or `update_metadata`.
+ * @param body - Parsed JSON request body (`threadId`, optional `metadata`).
+ * @param client - LangSmith client.
+ * @returns Thread/run record, or `void` for metadata updates.
+ * @throws {EnforcementError} On unknown action or disallowed metadata keys/title length.
+ */
 async function threadsCall(capability, action, body, client) {
     const threadId = bodyString(body, "threadId", "thread_id");
     if (action === "read") {
@@ -428,7 +747,13 @@ async function threadsCall(capability, action, body, client) {
     throw new EnforcementError(400, `unknown threads action "${action}"`);
 }
 // --- Response shaping ------------------------------------------------------
-/** Apply the capability's `include` allowlist, then drop any `redact` roots. */
+/**
+ * Apply the capability's `include` allowlist, then drop any `redact` roots.
+ *
+ * @param raw - Full LangSmith result coerced to a plain record.
+ * @param capability - Capability whose `response.include` / `response.redact` apply.
+ * @returns Allowlisted (and redacted) response object returned to the caller.
+ */
 export function shapeResponse(raw, capability) {
     const include = capability.response?.include ?? [];
     const redact = new Set(capability.response?.redact ?? []);
@@ -452,6 +777,13 @@ export function shapeResponse(raw, capability) {
     }
     return picked;
 }
+/**
+ * Walk a dotted path into a nested value.
+ *
+ * @param value - Root value to traverse.
+ * @param path - Remaining path segments after the root key.
+ * @returns Nested value at `path`, or `undefined` if any segment is missing.
+ */
 function pickNested(value, path) {
     let current = value;
     for (const segment of path) {
@@ -465,6 +797,13 @@ function pickNested(value, path) {
     return current;
 }
 // --- Helpers ---------------------------------------------------------------
+/**
+ * Extract the capability id from a `/capabilities/{id}` request URL.
+ *
+ * @param url - Absolute or relative request URL.
+ * @returns Decoded capability id path segment.
+ * @throws {EnforcementError} When the path has no `/capabilities/` marker.
+ */
 function capabilityIdFromUrl(url) {
     const { pathname } = new URL(url);
     const marker = "/capabilities/";
@@ -474,6 +813,13 @@ function capabilityIdFromUrl(url) {
     }
     return decodeURIComponent(pathname.slice(index + marker.length));
 }
+/**
+ * Parse the request body as a JSON object.
+ *
+ * @param request - Incoming HTTP request.
+ * @returns Parsed object body.
+ * @throws {EnforcementError} When the body is missing, non-JSON, or not an object.
+ */
 async function parseJsonBody(request) {
     try {
         const parsed = await request.json();
@@ -486,6 +832,14 @@ async function parseJsonBody(request) {
     }
     throw new EnforcementError(400, "request body must be a JSON object");
 }
+/**
+ * Read a required non-empty string field from the body.
+ *
+ * @param body - Parsed JSON request body.
+ * @param key - Exact field name to read.
+ * @returns Non-empty string value.
+ * @throws {EnforcementError} When the field is missing, non-string, or empty.
+ */
 function requireString(body, key) {
     const value = body[key];
     if (typeof value !== "string" || value.length === 0) {
@@ -493,7 +847,15 @@ function requireString(body, key) {
     }
     return value;
 }
-/** Read a required string from the body, accepting either camelCase or snake_case. */
+/**
+ * Read a required string from the body, accepting either camelCase or snake_case.
+ *
+ * @param body - Parsed JSON request body.
+ * @param camel - Preferred camelCase field name (used in error messages).
+ * @param snake - Alternate snake_case field name.
+ * @returns Non-empty string from either key.
+ * @throws {EnforcementError} When neither key yields a non-empty string.
+ */
 export function bodyString(body, camel, snake) {
     const value = optionalBodyString(body, camel, snake);
     if (value === undefined) {
@@ -501,6 +863,14 @@ export function bodyString(body, camel, snake) {
     }
     return value;
 }
+/**
+ * Read an optional string from the body, accepting either camelCase or snake_case.
+ *
+ * @param body - Parsed JSON request body.
+ * @param camel - Preferred camelCase field name.
+ * @param snake - Alternate snake_case field name.
+ * @returns Non-empty string from either key, or `undefined` when both are absent.
+ */
 function optionalBodyString(body, camel, snake) {
     const camelValue = body[camel];
     if (typeof camelValue === "string" && camelValue.length > 0) {
@@ -512,6 +882,14 @@ function optionalBodyString(body, camel, snake) {
     }
     return undefined;
 }
+/**
+ * Read a required plain-object field from the body.
+ *
+ * @param body - Parsed JSON request body.
+ * @param key - Field name to read.
+ * @returns Object value (not an array).
+ * @throws {EnforcementError} When the field is missing, not an object, or an array.
+ */
 function requireObject(body, key) {
     const value = body[key];
     if (!value || typeof value !== "object" || Array.isArray(value)) {
@@ -519,11 +897,28 @@ function requireObject(body, key) {
     }
     return value;
 }
+/**
+ * Enforce an optional allowlist for a string value.
+ *
+ * @param allowed - Allowed values, or `undefined` to skip the check.
+ * @param value - Candidate value.
+ * @param label - Field label used in the error message.
+ * @throws {EnforcementError} When `allowed` is set and does not include `value`.
+ */
 function assertAllowed(allowed, value, label) {
     if (allowed && !allowed.includes(value)) {
         throw new EnforcementError(400, `${label} "${value}" is not allowed`);
     }
 }
+/**
+ * Read an optional string comment/note from the body and enforce a max length.
+ *
+ * @param body - Parsed JSON request body.
+ * @param maxChars - Maximum allowed length, or `undefined` for no limit.
+ * @param field - Body field name (defaults to `"comment"`).
+ * @returns Trimmed-present string, or `undefined` when the field is nullish.
+ * @throws {EnforcementError} When the field is non-string or exceeds `maxChars`.
+ */
 function optionalComment(body, maxChars, field = "comment") {
     const value = body[field];
     if (value === undefined || value === null) {
@@ -537,13 +932,25 @@ function optionalComment(body, maxChars, field = "comment") {
     }
     return value;
 }
+/**
+ * Build a JSON HTTP response with a fixed content type.
+ *
+ * @param status - HTTP status code.
+ * @param body - Response payload (coerced via {@link jsonSafe}).
+ * @returns `Response` with `application/json` body.
+ */
 function jsonResponse(status, body) {
     return new Response(JSON.stringify(jsonSafe(body)), {
         status,
         headers: { "content-type": "application/json" },
     });
 }
-/** Coerce values LangSmith may return (Date, etc.) into JSON-serializable form. */
+/**
+ * Coerce values LangSmith may return (Date, etc.) into JSON-serializable form.
+ *
+ * @param value - Arbitrary value from the SDK or engine.
+ * @returns JSON-safe clone (Dates → ISO strings; objects/arrays walked recursively).
+ */
 function jsonSafe(value) {
     if (value === null || typeof value !== "object") {
         return value;
@@ -560,6 +967,12 @@ function jsonSafe(value) {
     }
     return out;
 }
+/**
+ * Map an unknown thrown value to an HTTP status for the error response.
+ *
+ * @param error - Caught value that is not an {@link EnforcementError}.
+ * @returns Status in `400..599` when present on the error; otherwise `502`.
+ */
 function statusFromUnknownError(error) {
     const status = error?.status;
     if (typeof status === "number" && status >= 400 && status <= 599) {
@@ -567,13 +980,24 @@ function statusFromUnknownError(error) {
     }
     return 502;
 }
+/**
+ * Extract a human-readable message from an unknown thrown value.
+ *
+ * @param error - Caught value.
+ * @returns `Error.message` when available; otherwise `"internal error"`.
+ */
 function errorMessage(error) {
     if (error instanceof Error) {
         return error.message;
     }
     return "internal error";
 }
-/** Coerce an SDK result (object | void | null) into a plain record for shaping. */
+/**
+ * Coerce an SDK result (object | void | null) into a plain record for shaping.
+ *
+ * @param value - Raw LangSmith call result.
+ * @returns Shallow-copied object, or `{}` when `value` is not an object.
+ */
 function toRecord(value) {
     if (value && typeof value === "object") {
         return { ...value };
@@ -587,6 +1011,8 @@ function toRecord(value) {
  *
  * A connector "score" is numeric/boolean → LangSmith `score`, or categorical
  * (string/object) → LangSmith feedback `value`.
+ *
+ * @returns `LangSmithClient` adapter over the official SDK.
  */
 export function defaultClient() {
     let client;
@@ -617,6 +1043,7 @@ export function defaultClient() {
             }
             return out;
         },
+        readFeedback: ({ feedbackId }) => sdk().readFeedback(feedbackId),
         readRun: ({ runId }) => sdk().readRun(runId),
         shareRun: async ({ runId }) => ({ url: await sdk().shareRun(runId) }),
         createExample: ({ dataset, inputs, outputs, metadata }) => sdk().createExample({