managed-deepagents 0.4.2 → 0.4.3-dev.95

package/dist/connectors/langsmith/routes.js

@@ -1,1182 +0,0 @@
-/**
- * LangSmith connector — runtime enforcement engine.
- *
- * Mounted by the connector's `http(ctx)` hook on its namespaced sub-router.
- * Exposes one uniform endpoint per capability:
- *
- *   POST /connectors/langsmith/capabilities/{capability_id}
- *
- * with a JSON body naming the `action` and its parameters. Per request the
- * engine resolves identity (resolve-or-401), checks the caller surface, checks
- * the action, proves capability ownership from `runtime.identity`, validates typed
- * constraints, performs the LangSmith operation server-side with the workspace
- * key, and returns an allowlisted response.
- *
- * v0 has no rate limiting, audit, or multi-workspace fan-out.
- */
-import { Client } from "langsmith";
-import { resolveLoopbackApiUrl } from "../../identity/loopback.js";
-import { ACTOR_HEADER, INGRESS_SECRET_HEADER, TENANT_HEADER, } from "../../runtime/auth.js";
-/** 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;
-        this.name = "EnforcementError";
-    }
-}
-/**
- * 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);
-    const deps = {
-        capabilitiesById: new Map(capabilities.map((c) => [c.id, c])),
-        client,
-        identityConfig: ctx.identity,
-    };
-    // Registered on the secure-by-default router, which resolves and enforces
-    // identity before this runs and injects the frozen identity as the handler's
-    // second argument.
-    ctx.router.post("/capabilities/:id", (request, identity) => handleCapabilityRequest(request, identity, deps));
-}
-/**
- * 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";
-    const tenancy = identity?.tenancy ?? "single";
-    for (const capability of capabilities) {
-        const externallyExposed = capability.exposeTo.length > 0;
-        const identityScoped = capability.scope === "actor" ||
-            capability.scope === "tenant" ||
-            capability.scope === "thread" ||
-            capability.scope === "run";
-        if (!identity) {
-            const readOnly = capability.actions.every((a) => a.startsWith("read"));
-            if (externallyExposed && !(capability.scope === "agent" && readOnly)) {
-                throw new Error(`LangSmith capability "${capability.id}" is exposed externally but the ` +
-                    `deployment has no identity configured. Only agent-scoped, read-only ` +
-                    `capabilities may be exposed without identity.`);
-            }
-            continue;
-        }
-        if (capability.scope === "tenant" && tenancy === "single") {
-            throw new Error(`LangSmith capability "${capability.id}" is tenant-scoped but the ` +
-                `deployment is tenancy: "single".`);
-        }
-        if (capability.exposeTo.includes("browser") &&
-            identityScoped &&
-            !hasValidatedToken) {
-            throw new Error(`LangSmith capability "${capability.id}" is ${capability.scope}-scoped and ` +
-                `exposed to browser, but the deployment has no validated_token ingress ` +
-                `to resolve an end-user identity.`);
-        }
-    }
-}
-/**
- * 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);
-        const capability = deps.capabilitiesById.get(capabilityId);
-        if (!capability) {
-            throw new EnforcementError(404, `unknown capability "${capabilityId}"`);
-        }
-        const surface = callerSurface(identity, deps.identityConfig);
-        if (!capability.exposeTo.includes(surface)) {
-            throw new EnforcementError(403, `capability "${capability.id}" is not exposed to ${surface}`);
-        }
-        const body = await parseJsonBody(request);
-        const action = String(body.action ?? "");
-        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. 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);
-        return jsonResponse(200, { data: shaped });
-    }
-    catch (error) {
-        if (error instanceof EnforcementError) {
-            return jsonResponse(error.status, { error: error.message });
-        }
-        const status = statusFromUnknownError(error);
-        return jsonResponse(status, { error: errorMessage(error) });
-    }
-}
-/**
- * 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") {
-        return "channel";
-    }
-    if (provider === "schedule") {
-        return "schedule";
-    }
-    // http / cli: browser vs trusted_backend depends on the ingress mode.
-    return identityConfig?.ingress.http === "trusted_backend"
-        ? "trusted_backend"
-        : "browser";
-}
-// --- Ownership + constraints -----------------------------------------------
-/**
- * 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
-        ? threadId
-        : undefined;
-}
-/**
- * Attach a proven thread id onto a copy of the identity envelope.
- * Returns the same object when the identity already carries that thread id.
- *
- * @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 withIdentityThread(identity, threadId) {
-    if (identityThreadId(identity) === threadId) {
-        return identity;
-    }
-    return {
-        ...identity,
-        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");
-        }
-        // Server-local Agent Server origin only — never derive from request.url /
-        // Host (attacker-controlled and would turn this credentialed GET into SSRF).
-        const origin = resolveLoopbackApiUrl();
-        const threadUrl = new URL(`/threads/${encodeURIComponent(threadId)}`, origin.endsWith("/") ? origin : `${origin}/`);
-        const headers = forwardAuthHeaders(request);
-        let response;
-        try {
-            response = await fetch(threadUrl, {
-                method: "GET",
-                headers,
-                redirect: "manual",
-            });
-        }
-        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",
-    INGRESS_SECRET_HEADER,
-    ACTOR_HEADER,
-    TENANT_HEADER,
-];
-/**
- * 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. 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) {
-        case "agent":
-            return;
-        case "actor": {
-            const actorId = identity.actor?.id;
-            if (typeof actorId !== "string" || actorId.length === 0) {
-                throw new EnforcementError(403, "actor scope requires identity.actor.id");
-            }
-            return;
-        }
-        case "tenant": {
-            const tenantId = identity.tenant?.id;
-            if (typeof tenantId !== "string" || tenantId.length === 0) {
-                throw new EnforcementError(403, "tenant scope requires identity.tenant.id");
-            }
-            return;
-        }
-        case "thread": {
-            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, 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 run = toRecord(await client.readRun({ runId }));
-            const runThread = runThreadId(run);
-            if (!runThread || runThread !== threadId) {
-                throw new EnforcementError(403, "run does not belong to identity thread");
-            }
-            return;
-        }
-        default:
-            throw new EnforcementError(400, `unknown capability scope "${String(capability.scope)}"`);
-    }
-}
-/**
- * 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 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;
-        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;
-            }
-        }
-    }
-    return undefined;
-}
-/**
- * Normalize LangSmith id fields to a non-empty string.
- * Python SDK returns `uuid.UUID`; JS JSON is usually already a string.
- *
- * @param value - Raw id from a body field or LangSmith SDK object.
- * @returns Non-empty string id, or `undefined`.
- */
-function asIdString(value) {
-    if (typeof value === "string" && value.length > 0) {
-        return value;
-    }
-    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 }));
-    return asIdString(feedback.run_id ?? feedback.runId);
-}
-/**
- * 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)) {
-        const actorId = direct.mda_actor_id;
-        if (typeof actorId === "string" && actorId.length > 0) {
-            return actorId;
-        }
-    }
-    const source = feedback.feedback_source;
-    if (source && typeof source === "object" && !Array.isArray(source)) {
-        const metadata = source.metadata;
-        if (metadata && typeof metadata === "object" && !Array.isArray(metadata)) {
-            const actorId = metadata.mda_actor_id;
-            if (typeof actorId === "string" && actorId.length > 0) {
-                return actorId;
-            }
-        }
-    }
-    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)) {
-        const threadId = metadata.mda_thread_id;
-        if (typeof threadId === "string" && threadId.length > 0) {
-            return threadId;
-        }
-    }
-    return undefined;
-}
-/**
- * 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":
-            return feedbackCall(capability, action, body, deps.client, identity);
-        case "runs":
-            return runsCall(action, body, deps.client);
-        case "examples":
-            return examplesCall(capability, body, deps.client, identity);
-        case "annotation_queues":
-            return annotationQueueCall(capability, body, deps.client);
-        case "prompts":
-            return deps.client.readPrompt({ name: requireString(body, "name") });
-        case "threads":
-            return threadsCall(capability, action, body, deps.client);
-        default:
-            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") {
-        const key = requireString(body, "key");
-        assertAllowed(c.keys, key, "key");
-        // Validated against the `scores` allowlist, then handed to the SDK as a
-        // categorical score/value (see LangSmithClient docs).
-        const score = body.score;
-        if (score !== undefined) {
-            assertAllowed(c.scores, String(score), "score");
-        }
-        const comment = optionalComment(body, c.maxCommentChars);
-        const runId = bodyString(body, "runId", "run_id");
-        const actorId = identity.actor?.id;
-        if (c.onePerActor === true) {
-            if (typeof actorId !== "string" || actorId.length === 0) {
-                throw new EnforcementError(403, "onePerActor requires identity.actor.id");
-            }
-            const existing = await client.listFeedbackForRun({ runId });
-            for (const feedback of existing) {
-                if (feedbackActorId(toRecord(feedback)) === actorId) {
-                    throw new EnforcementError(409, "actor already submitted feedback for this run");
-                }
-            }
-        }
-        const metadata = typeof actorId === "string" && actorId.length > 0
-            ? { mda_actor_id: actorId }
-            : undefined;
-        const feedbackId = optionalBodyString(body, "feedbackId", "feedback_id");
-        return client.createFeedback({
-            runId,
-            key,
-            ...(score !== undefined ? { score } : {}),
-            ...(comment !== undefined ? { comment } : {}),
-            ...(feedbackId !== undefined ? { feedbackId } : {}),
-            ...(metadata ? { metadata } : {}),
-        });
-    }
-    if (action === "update") {
-        const comment = optionalComment(body, c.maxCommentChars);
-        const score = body.score;
-        return client.updateFeedback({
-            feedbackId: bodyString(body, "feedbackId", "feedback_id"),
-            ...(score !== undefined ? { score } : {}),
-            ...(comment !== undefined ? { comment } : {}),
-        });
-    }
-    if (action === "delete") {
-        return client.deleteFeedback({
-            feedbackId: bodyString(body, "feedbackId", "feedback_id"),
-        });
-    }
-    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") {
-        return client.readRun({ runId });
-    }
-    if (action === "share") {
-        return client.shareRun({ runId });
-    }
-    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;
-    if (!dataset) {
-        throw new EnforcementError(400, "examples capability has no dataset");
-    }
-    const inputs = requireObject(body, "inputs");
-    const allowedFields = c.allowedFields;
-    if (allowedFields) {
-        for (const field of Object.keys(inputs)) {
-            if (!allowedFields.includes(field)) {
-                throw new EnforcementError(400, `field "${field}" is not allowed`);
-            }
-        }
-    }
-    const outputs = body.outputs && typeof body.outputs === "object"
-        ? body.outputs
-        : undefined;
-    const maxExamples = c.maxExamplesPerThread;
-    const threadId = identityThreadId(identity);
-    if (typeof maxExamples === "number") {
-        if (!threadId) {
-            throw new EnforcementError(403, "maxExamplesPerThread requires identity thread id");
-        }
-        const existing = await client.listExamples({
-            dataset,
-            metadata: { mda_thread_id: threadId },
-        });
-        const count = existing.filter((example) => exampleThreadId(toRecord(example)) === threadId).length;
-        if (count >= maxExamples) {
-            throw new EnforcementError(409, `thread already has ${maxExamples} examples in this dataset`);
-        }
-    }
-    const metadata = {};
-    if (threadId) {
-        metadata.mda_thread_id = threadId;
-    }
-    const actorId = identity.actor?.id;
-    if (typeof actorId === "string" && actorId.length > 0) {
-        metadata.mda_actor_id = actorId;
-    }
-    return client.createExample({
-        dataset,
-        inputs,
-        ...(outputs ? { outputs } : {}),
-        ...(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;
-    if (!queue) {
-        throw new EnforcementError(400, "annotation queue capability has no queue");
-    }
-    const priority = body.priority;
-    if (priority !== undefined) {
-        assertAllowed(c.allowedPriorities, String(priority), "priority");
-    }
-    const note = optionalComment(body, c.maxNoteChars, "note");
-    return client.enqueueRun({
-        queue,
-        runId: bodyString(body, "runId", "run_id"),
-        ...(typeof priority === "string" ? { priority } : {}),
-        ...(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") {
-        return client.readThread({ threadId });
-    }
-    if (action === "update_metadata") {
-        const c = capability.constraints ?? {};
-        const metadata = requireObject(body, "metadata");
-        const metadataKeys = c.metadataKeys;
-        if (metadataKeys) {
-            for (const key of Object.keys(metadata)) {
-                if (!metadataKeys.includes(key)) {
-                    throw new EnforcementError(400, `metadata key "${key}" is not allowed`);
-                }
-            }
-        }
-        const maxTitle = c.maxTitleChars;
-        if (maxTitle !== undefined && typeof metadata.title === "string") {
-            if (metadata.title.length > maxTitle) {
-                throw new EnforcementError(400, `title exceeds ${maxTitle} characters`);
-            }
-        }
-        return client.updateThreadMetadata({ threadId, metadata });
-    }
-    throw new EnforcementError(400, `unknown threads action "${action}"`);
-}
-// --- Response shaping ------------------------------------------------------
-/**
- * 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 ?? []);
-    const picked = {};
-    for (const path of include) {
-        const [root, ...rest] = path.split(".");
-        if (root === undefined || redact.has(root)) {
-            continue;
-        }
-        if (rest.length === 0) {
-            if (root in raw) {
-                picked[root] = raw[root];
-            }
-            continue;
-        }
-        const nested = pickNested(raw[root], rest);
-        if (nested !== undefined) {
-            const existing = picked[root] ?? {};
-            picked[root] = { ...existing, [rest.join(".")]: nested };
-        }
-    }
-    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) {
-        if (current && typeof current === "object" && segment in current) {
-            current = current[segment];
-        }
-        else {
-            return undefined;
-        }
-    }
-    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/";
-    const index = pathname.lastIndexOf(marker);
-    if (index === -1) {
-        throw new EnforcementError(404, "capability id missing from path");
-    }
-    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();
-        if (parsed && typeof parsed === "object") {
-            return parsed;
-        }
-    }
-    catch {
-        // fall through to the uniform error below
-    }
-    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) {
-        throw new EnforcementError(400, `missing or invalid "${key}"`);
-    }
-    return value;
-}
-/**
- * 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) {
-        throw new EnforcementError(400, `missing or invalid "${camel}"`);
-    }
-    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) {
-        return camelValue;
-    }
-    const snakeValue = body[snake];
-    if (typeof snakeValue === "string" && snakeValue.length > 0) {
-        return snakeValue;
-    }
-    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)) {
-        throw new EnforcementError(400, `missing or invalid "${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) {
-        return undefined;
-    }
-    if (typeof value !== "string") {
-        throw new EnforcementError(400, `"${field}" must be a string`);
-    }
-    if (maxChars !== undefined && value.length > maxChars) {
-        throw new EnforcementError(400, `"${field}" exceeds ${maxChars} characters`);
-    }
-    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.
- *
- * @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;
-    }
-    if (value instanceof Date) {
-        return value.toISOString();
-    }
-    if (Array.isArray(value)) {
-        return value.map(jsonSafe);
-    }
-    const out = {};
-    for (const [key, nested] of Object.entries(value)) {
-        out[key] = jsonSafe(nested);
-    }
-    return out;
-}
-/**
- * Map an unknown thrown value to an HTTP status for the error response.
- *
- * Prefers an explicit status on the error (or its `response`), then status
- * codes embedded in SDK messages, then `502` when nothing recoverable is
- * present. Mirrors the Python connector's `_status_from_unknown_error`.
- *
- * @param error - Caught value that is not an {@link EnforcementError}.
- * @returns Status in `400..599` when recoverable; otherwise `502`.
- */
-function statusFromUnknownError(error) {
-    const seen = new Set();
-    let current = error;
-    while (current != null && typeof current === "object" && !seen.has(current)) {
-        seen.add(current);
-        const record = current;
-        const direct = coerceHttpErrorStatus(record.status ?? record.statusCode);
-        if (direct !== undefined) {
-            return direct;
-        }
-        const response = record.response;
-        if (response != null && typeof response === "object") {
-            const nested = response;
-            const fromResponse = coerceHttpErrorStatus(nested.status ?? nested.statusCode);
-            if (fromResponse !== undefined) {
-                return fromResponse;
-            }
-        }
-        const name = typeof record.name === "string" ? record.name : undefined;
-        if (name === "LangSmithNotFoundError") {
-            return 404;
-        }
-        if (name === "LangSmithConflictError") {
-            return 409;
-        }
-        const message = current instanceof Error
-            ? current.message
-            : typeof record.message === "string"
-                ? record.message
-                : String(current);
-        const fromMessage = statusFromErrorMessage(message);
-        if (fromMessage !== undefined) {
-            return fromMessage;
-        }
-        current = record.cause;
-    }
-    return 502;
-}
-/** Return `value` when it is an HTTP error status in `400..599`. */
-function coerceHttpErrorStatus(value) {
-    if (typeof value === "number" && value >= 400 && value <= 599) {
-        return value;
-    }
-    return undefined;
-}
-/**
- * Recover an HTTP status embedded in LangSmith / requests-style error text.
- *
- * @param message - Error message that may mention an upstream status.
- * @returns Status in `400..599` when found; otherwise `undefined`.
- */
-function statusFromErrorMessage(message) {
-    const patterns = [
-        /Received status \[([45]\d{2})\]/,
-        /\b([45]\d{2}) Client Error\b/,
-        /\b([45]\d{2}) Server Error\b/,
-        /\bHTTPError\(['"]([45]\d{2})\b/,
-    ];
-    for (const pattern of patterns) {
-        const match = pattern.exec(message);
-        if (match) {
-            return coerceHttpErrorStatus(Number(match[1]));
-        }
-    }
-    return undefined;
-}
-/**
- * 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.
- *
- * @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 };
-    }
-    return {};
-}
-/**
- * Resolve the LangSmith workspace id used for `X-Tenant-Id`.
- *
- * Org-scoped / multi-workspace API keys default to the key's home workspace
- * unless scoped. Prefer `LANGSMITH_WORKSPACE_ID` (SDK standard); fall back to
- * `LANGSMITH_TENANT_ID` (deploy CLI / platform legacy name for the same id).
- *
- * @param env - Environment map; defaults to `process.env`.
- * @returns Trimmed workspace id, or `undefined` when unset.
- */
-export function resolveLangSmithWorkspaceId(env = process.env) {
-    for (const key of [
-        "LANGSMITH_WORKSPACE_ID",
-        "LANGCHAIN_WORKSPACE_ID",
-        "LANGSMITH_TENANT_ID",
-        "LANGCHAIN_TENANT_ID",
-    ]) {
-        const value = env[key]?.trim();
-        if (value)
-            return value;
-    }
-    return undefined;
-}
-/**
- * Default client backed by the `langsmith` SDK {@link Client}. The underlying
- * client is created on first use so building the engine (e.g. for an app with no
- * requests yet) never requires `LANGSMITH_API_KEY`.
- *
- * Passes {@link resolveLangSmithWorkspaceId} so run/feedback calls target the
- * deployment workspace rather than the API key's default tenant.
- *
- * 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;
-    const sdk = () => {
-        client ??= new Client({
-            apiKey: process.env.LANGSMITH_API_KEY,
-            workspaceId: resolveLangSmithWorkspaceId(),
-        });
-        return client;
-    };
-    const isScore = (value) => typeof value === "number" || typeof value === "boolean" || value === null;
-    const scoreOrValue = (value) => {
-        if (isScore(value)) {
-            return { score: value };
-        }
-        return value === undefined ? {} : { value };
-    };
-    return {
-        createFeedback: ({ runId, key, score, comment, feedbackId, metadata }) => sdk().createFeedback(runId, key, {
-            ...scoreOrValue(score),
-            comment,
-            feedbackId,
-            ...(metadata ? { sourceInfo: metadata } : {}),
-        }),
-        updateFeedback: ({ feedbackId, score, comment }) => sdk().updateFeedback(feedbackId, { ...scoreOrValue(score), comment }),
-        deleteFeedback: ({ feedbackId }) => sdk().deleteFeedback(feedbackId),
-        listFeedbackForRun: async ({ runId }) => {
-            const out = [];
-            for await (const feedback of sdk().listFeedback({ runIds: [runId] })) {
-                out.push(feedback);
-            }
-            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({
-            inputs,
-            outputs,
-            dataset_name: dataset,
-            ...(metadata ? { metadata } : {}),
-        }),
-        listExamples: async ({ dataset, metadata }) => {
-            const out = [];
-            for await (const example of sdk().listExamples({
-                datasetName: dataset,
-                ...(metadata ? { metadata } : {}),
-            })) {
-                out.push(example);
-            }
-            return out;
-        },
-        enqueueRun: ({ queue, runId }) => sdk().addRunsToAnnotationQueue(queue, [runId]),
-        readPrompt: ({ name }) => sdk().getPrompt(name),
-        readThread: ({ threadId }) => sdk().readRun(threadId),
-        updateThreadMetadata: ({ threadId, metadata }) => sdk().updateRun(threadId, { extra: metadata }),
-    };
-}
-//# sourceMappingURL=routes.js.map