@lucern/sdk 0.2.0-alpha.4 → 0.2.0-alpha.5

package/dist/{packages/sdk/src → lib/platform/sdk}/graphClient.d.ts

@@ -3,7 +3,9 @@ import type { DeleteEdgeResponse, GraphAnalyticsMetric, GraphAnalyticsResponse,
 export { LucernApiError };
 export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
 export type { CreateEdgeResponse, CreateNodeResponse, DeleteEdgeResponse, GraphAnalyticsMetric, GraphAnalyticsResponse, GraphNeighborhoodResponse, GraphPathResponse, ListResult, QueryEdgesResponse, QueryNodesResponse, UpdateNodeResponse, } from "./types";
+/** Configuration for the graph client. */
 export type GraphClientConfig = GatewayClientConfig;
+/** Filter parameters for listing graph nodes. */
 export type ListNodesInput = {
     nodeId?: string;
     globalId?: string;
@@ -11,8 +13,11 @@ export type ListNodesInput = {
     nodeType?: string;
     limit?: number;
 } & TopicIdentifierInput;
+/** Paginated list response containing graph nodes. */
 export type ListNodesResponse = ListResult<PlatformGraphNode, "nodes">;
+/** @deprecated Use ListNodesInput. */
 export type QueryNodesInput = ListNodesInput;
+/** Input for creating a new graph node. */
 export type CreateNodeInput = {
     text?: string;
     /** @deprecated Use text. */
@@ -31,6 +36,7 @@ export type CreateNodeInput = {
     metadata?: JsonObject;
     verificationStatus?: string;
 } & TextAliasInput & TopicIdentifierInput;
+/** Input for updating an existing graph node. */
 export type UpdateNodeInput = {
     nodeId: string;
     text?: string;
@@ -45,6 +51,12 @@ export type UpdateNodeInput = {
     metadata?: JsonObject;
     verificationStatus?: string;
 } & TextAliasInput;
+/** Input for retrieving a single graph node by canonical identifier. */
+export type GetNodeInput = {
+    nodeId?: string;
+    globalId?: string;
+};
+/** Filter parameters for listing graph edges. */
 export type ListEdgesInput = {
     edgeId?: string;
     topicId?: string;
@@ -53,8 +65,11 @@ export type ListEdgesInput = {
     edgeType?: string;
     limit?: number;
 } & TopicIdentifierInput;
+/** Paginated list response containing graph edges. */
 export type ListEdgesResponse = ListResult<PlatformGraphEdge, "edges">;
+/** @deprecated Use ListEdgesInput. */
 export type QueryEdgesInput = ListEdgesInput;
+/** Input for creating a typed edge between two graph nodes. */
 export type CreateEdgeInput = {
     fromNodeId: string;
     toNodeId: string;
@@ -66,46 +81,84 @@ export type CreateEdgeInput = {
     context?: string;
     derivationType?: string;
 } & TopicIdentifierInput;
+/** Filter for selecting edges to delete. */
 export type DeleteEdgeInput = {
     edgeId?: string;
     fromNodeId?: string;
     toNodeId?: string;
     edgeType?: string;
 };
+/** Input for batch-creating multiple graph nodes. */
+export type BatchCreateNodesInput = {
+    nodes: Array<CreateNodeInput>;
+};
+/** Input for superseding an existing graph node with a new version. */
+export type SupersedeNodeInput = {
+    oldNodeId?: string;
+    nodeId?: string;
+    newGlobalId?: string;
+    newCanonicalText?: string;
+    text?: string;
+    canonicalText?: string;
+    newContentHash?: string;
+    reason?: string;
+};
+/** Input for updating a node's verification state. */
+export type VerifyNodeInput = {
+    nodeId?: string;
+    id?: string;
+    verificationStatus: string;
+    confidence?: number;
+};
+/** Input for permanently deleting a node via admin-only API. */
+export type HardDeleteNodeInput = {
+    nodeId?: string;
+    id?: string;
+    reason: string;
+    allowBeliefHardDelete?: boolean;
+};
+/** Input for retrieving the local neighborhood around a graph node. */
 export type NeighborhoodInput = {
     globalId?: string;
     globalIds?: string;
     maxDepth?: number;
 };
+/** Input for finding the shortest path between two graph nodes. */
 export type PathInput = {
     fromGlobalId: string;
     toGlobalId: string;
     maxDepth?: number;
 };
+/** Input for retrieving a specific graph analytics metric. */
 export type AnalyticsInput = {
     metric?: GraphAnalyticsMetric;
     limit?: number;
 };
+/** Input for traversing the graph from a starting node. */
 export type TraverseInput = {
     startNode: string;
     direction?: string;
     maxDepth?: number;
     topicId?: string;
 } & TopicIdentifierInput;
+/** Input for structural analysis of a topic graph. */
 export type AnalyzeInput = {
     topicId?: string;
     metric?: GraphAnalyticsMetric;
     limit?: number;
 } & TopicIdentifierInput;
+/** Input for detecting confirmation-bias patterns in a topic graph. */
 export type BiasInput = {
     topicId?: string;
     threshold?: number;
     limit?: number;
 } & TopicIdentifierInput;
+/** Input for finding beliefs without sufficient testing questions. */
 export type GapsInput = {
     topicId?: string;
     minConfidence?: number;
 } & TopicIdentifierInput;
+/** Input for cross-resource search within a topic scope. */
 export type SearchInput = {
     q?: string;
     query?: string;
@@ -118,6 +171,8 @@ export type SearchInput = {
 } & TopicIdentifierInput;
 /**
  * Create the low-level graph client for nodes, edges, and graph analytics.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods for CRUD on nodes/edges plus analytics, traversal, and search.
  */
 export declare function createGraphClient(config?: GraphClientConfig): {
     /**
@@ -128,6 +183,10 @@ export declare function createGraphClient(config?: GraphClientConfig): {
      * @deprecated Use listNodes.
      */
     queryNodes(query: QueryNodesInput): Promise<import("./coreClient").PlatformGatewaySuccess<ListResult<PlatformGraphNode, "nodes">>>;
+    /**
+     * Retrieve a single graph node by nodeId or globalId.
+     */
+    getNode(query: GetNodeInput): Promise<import("./coreClient").PlatformGatewaySuccess<PlatformGraphNode>>;
     /**
      * Create a graph node.
      */
@@ -136,6 +195,22 @@ export declare function createGraphClient(config?: GraphClientConfig): {
      * Update a graph node.
      */
     updateNode(input: UpdateNodeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<PlatformGraphNode>>;
+    /**
+     * Batch create graph nodes through the admin route surface.
+     */
+    batchCreateNodes(input: BatchCreateNodesInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Supersede an existing graph node with a new canonical version.
+     */
+    supersedeNode(input: SupersedeNodeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Update a node's verification status.
+     */
+    verifyNode(input: VerifyNodeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
+    /**
+     * Permanently delete a node via the admin-only hard-delete route.
+     */
+    hardDeleteNode(input: HardDeleteNodeInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<Record<string, unknown>>>;
     /**
      * List graph edges matching the provided filters.
      */

package/dist/lib/platform/sdk/graphClient.js

@@ -0,0 +1,235 @@
+import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, toQueryString, } from "./coreClient.js";
+import { mapAliasedList, mapGatewayData, normalizeNodeWriteInput, normalizeNodeVerificationStatus, normalizeTopicQuery, withSdkAliases, } from "./sdkSurface.js";
+export { LucernApiError };
+/**
+ * Create the low-level graph client for nodes, edges, and graph analytics.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods for CRUD on nodes/edges plus analytics, traversal, and search.
+ */
+export function createGraphClient(config = {}) {
+    const gateway = createGatewayRequestClient(config);
+    return {
+        /**
+         * List graph nodes matching the provided filters.
+         */
+        async listNodes(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/nodes${toQueryString(normalizeTopicQuery(query))}`,
+            }).then((response) => mapGatewayData(response, (data) => mapAliasedList(data, "nodes")));
+        },
+        /**
+         * @deprecated Use listNodes.
+         */
+        async queryNodes(query) {
+            return this.listNodes(query);
+        },
+        /**
+         * Retrieve a single graph node by nodeId or globalId.
+         */
+        async getNode(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/nodes${toQueryString(query)}`,
+            }).then((response) => mapGatewayData(response, (data) => withSdkAliases(data)));
+        },
+        /**
+         * Create a graph node.
+         */
+        async createNode(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/graph/nodes",
+                method: "POST",
+                body: normalizeNodeWriteInput(input),
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withSdkAliases(data)));
+        },
+        /**
+         * Update a graph node.
+         */
+        async updateNode(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/graph/nodes",
+                method: "PUT",
+                body: normalizeNodeWriteInput(input),
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            }).then((response) => mapGatewayData(response, (data) => withSdkAliases(data)));
+        },
+        /**
+         * Batch create graph nodes through the admin route surface.
+         */
+        async batchCreateNodes(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/graph/nodes/batch",
+                method: "POST",
+                body: {
+                    nodes: input.nodes.map((node) => normalizeNodeWriteInput(node)),
+                },
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Supersede an existing graph node with a new canonical version.
+         */
+        async supersedeNode(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/graph/nodes/supersede",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Update a node's verification status.
+         */
+        async verifyNode(input, idempotencyKey) {
+            const verificationStatus = normalizeNodeVerificationStatus(input.verificationStatus) ??
+                input.verificationStatus;
+            return gateway.request({
+                path: "/api/platform/v1/graph/nodes/verify",
+                method: "POST",
+                body: {
+                    ...input,
+                    verificationStatus,
+                },
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Permanently delete a node via the admin-only hard-delete route.
+         */
+        async hardDeleteNode(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/graph/nodes/hard-delete",
+                method: "POST",
+                body: input,
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * List graph edges matching the provided filters.
+         */
+        async listEdges(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/edges${toQueryString(normalizeTopicQuery(query))}`,
+            }).then((response) => mapGatewayData(response, (data) => mapAliasedList(data, "edges")));
+        },
+        /**
+         * @deprecated Use listEdges.
+         */
+        async queryEdges(query) {
+            return this.listEdges(query);
+        },
+        /**
+         * Create a graph edge.
+         */
+        async createEdge(input, idempotencyKey) {
+            return gateway.request({
+                path: "/api/platform/v1/graph/edges",
+                method: "POST",
+                body: normalizeTopicQuery(input),
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Delete one or more edges matching the provided filter.
+         */
+        async deleteEdge(query, idempotencyKey) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/edges${toQueryString(query)}`,
+                method: "DELETE",
+                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+            });
+        },
+        /**
+         * Retrieve a graph neighborhood around a root node.
+         */
+        async neighborhood(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/neighborhood${toQueryString(query)}`,
+            });
+        },
+        /**
+         * Traverse the graph from a starting node.
+         */
+        async traverse(query) {
+            return gateway.request({
+                path: "/api/platform/v1/graph/traverse",
+                method: "POST",
+                body: normalizeTopicQuery(query),
+            });
+        },
+        /**
+         * Analyze graph structure for a topic.
+         */
+        async analyze(query = {}) {
+            const normalized = normalizeTopicQuery(query);
+            return gateway.request({
+                path: `/api/platform/v1/graph/analyze${toQueryString({
+                    topicId: typeof normalized.topicId === "string" ? normalized.topicId : undefined,
+                    metric: typeof normalized.metric === "string" ? normalized.metric : undefined,
+                    limit: typeof normalized.limit === "number" ? normalized.limit : undefined,
+                })}`,
+            });
+        },
+        /**
+         * Detect confirmation-bias patterns for a topic graph.
+         */
+        async bias(query = {}) {
+            const normalized = normalizeTopicQuery(query);
+            return gateway.request({
+                path: `/api/platform/v1/graph/bias${toQueryString({
+                    topicId: typeof normalized.topicId === "string" ? normalized.topicId : undefined,
+                    threshold: typeof normalized.threshold === "number"
+                        ? normalized.threshold
+                        : undefined,
+                    limit: typeof normalized.limit === "number" ? normalized.limit : undefined,
+                })}`,
+            });
+        },
+        /**
+         * Find graph gaps for beliefs that still need testing.
+         */
+        async gaps(query) {
+            const normalized = normalizeTopicQuery(query);
+            return gateway.request({
+                path: `/api/platform/v1/graph/gaps${toQueryString({
+                    topicId: typeof normalized.topicId === "string" ? normalized.topicId : undefined,
+                    minConfidence: typeof normalized.minConfidence === "number"
+                        ? normalized.minConfidence
+                        : undefined,
+                })}`,
+            });
+        },
+        /**
+         * Search across graph resources within a topic.
+         */
+        async search(query) {
+            return gateway.request({
+                path: "/api/platform/v1/search",
+                method: "POST",
+                body: normalizeTopicQuery(query),
+            });
+        },
+        /**
+         * Retrieve a graph neighborhood around a root node.
+         */
+        async getNeighborhood(query) {
+            return this.neighborhood(query);
+        },
+        /**
+         * Retrieve the shortest known path between two graph nodes.
+         */
+        async getPath(query) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/path${toQueryString(query)}`,
+            });
+        },
+        /**
+         * Retrieve graph analytics for the requested metric.
+         */
+        async getAnalytics(query = {}) {
+            return gateway.request({
+                path: `/api/platform/v1/graph/analytics${toQueryString(query)}`,
+            });
+        },
+    };
+}

package/dist/{packages/sdk/src → lib/platform/sdk}/harnessClient.d.ts

@@ -2,7 +2,23 @@ import { type GatewayClientConfig, type GatewayScope, LucernApiError } from "./c
 import type { JsonObject, JsonValue, TopicIdentifierInput } from "./types";
 export { LucernApiError };
 export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+/** Configuration for the harness client. Inherits gateway transport settings. */
 export type HarnessClientConfig = GatewayClientConfig;
+export type HarnessAgentGuardrails = {
+    isolationMode?: "direct" | "sandbox";
+    maxExecutionMs?: number;
+    heartbeatIntervalMs?: number;
+    maxToolCalls?: number;
+    allowNetworkEgress?: boolean;
+    allowedOrigins?: string[];
+};
+export type HarnessAgentRuntimeConfig = {
+    entryPoint?: string;
+    callbackUrl?: string;
+    modelRouting?: "model_machine" | "tenant_proxy" | "bring_your_own";
+    auditMode?: "harness" | "master_control";
+};
+/** Input for creating or updating an agent definition in the harness registry. */
 export type HarnessAgentWriteInput = GatewayScope & {
     agentDefinitionId?: string;
     agentKey: string;
@@ -13,13 +29,22 @@ export type HarnessAgentWriteInput = GatewayScope & {
     executionAdapter: "convex_mutation" | "convex_action" | "http_callback" | "mcp_tool" | "sdk_invocation" | "external_observed";
     scopeRequirements?: string[];
     promptReleaseChannel?: "dev" | "staging" | "prod";
+    promptName?: string;
+    systemPrompt?: string;
+    toolIds?: string[];
+    modelSlot?: string;
+    requiredModelCapabilities?: string[];
     parameterSchema?: JsonObject;
+    outputSchema?: JsonObject;
+    guardrails?: HarnessAgentGuardrails;
+    runtimeConfig?: HarnessAgentRuntimeConfig;
     exampleInvocations?: Array<{
         input: JsonObject;
         expectedOutput?: JsonValue;
     }>;
     metadata?: JsonObject;
 };
+/** Input for creating or updating a tool definition in the harness registry. */
 export type HarnessToolWriteInput = GatewayScope & {
     toolId?: string;
     toolName: string;
@@ -48,17 +73,72 @@ export type HarnessToolWriteInput = GatewayScope & {
     }>;
     metadata?: JsonObject;
 };
+export type HarnessExecuteToolInput = GatewayScope & {
+    input?: JsonObject;
+    version?: string;
+    transportKind?: string;
+};
+export type HarnessExecuteToolResult = {
+    tool: {
+        toolId: string;
+        toolName: string;
+        version: string;
+        status: "active" | "deprecated" | "disabled";
+        executionAdapter: "convex_mutation" | "convex_action" | "http_callback" | "mcp_tool" | "sdk_invocation" | "external_observed";
+        gateClassification: "core" | "shimmed";
+        scopeRequirements: string[];
+        safetyMetadata: {
+            readOnly: boolean;
+            idempotent: boolean;
+            sideEffectLevel: "none" | "low" | "high";
+        };
+    };
+    execution: {
+        input: JsonObject;
+        transportKind: string;
+        startedAt: number;
+        completedAt: number;
+        durationMs: number;
+    };
+    envelope: JsonObject | null;
+    audit: {
+        toolName: string;
+        contractName: string;
+        transportKind: string;
+        authMode: string;
+        requiredScopes: string[];
+        source: "gateway_envelope";
+        isError: boolean;
+        code?: string;
+        status?: number;
+        correlationId?: string | null;
+        policyTraceId?: string | null;
+        invariant?: string | null;
+    } | null;
+    output: {
+        isError: boolean;
+        parsed: JsonValue;
+        raw: JsonValue;
+    };
+};
+/** Input for starting a new harness run (agent execution session). */
 export type HarnessStartRunInput = GatewayScope & {
     agentDefinitionId: string;
     agentVersion: string;
     executionAdapter: "convex_mutation" | "convex_action" | "http_callback" | "mcp_tool" | "sdk_invocation" | "external_observed";
     promptReleaseChannel?: "dev" | "staging" | "prod";
     chatId?: string;
-    sprintId?: string;
+    worktreeId?: string;
     topicId?: string;
     langfuseTraceId?: string;
     metadata?: JsonObject;
 } & TopicIdentifierInput;
+export type HarnessInvokeManagedAgentInput = GatewayScope & {
+    agentDefinitionId: string;
+    input?: JsonObject;
+    metadata?: JsonObject;
+};
+/** Input for reporting a ledger event (tool call, prompt resolution, or policy decision) within a run. */
 export type HarnessRunReportInput = {
     reportingToken: string;
     type: "tool_call" | "prompt_resolution" | "policy_decision";
@@ -89,6 +169,7 @@ export type HarnessRunReportInput = {
         details?: JsonValue;
     };
 };
+/** Input for completing a harness run with a terminal status. */
 export type HarnessCompleteRunInput = {
     reportingToken: string;
     status: "completed" | "failed" | "timeout";
@@ -126,6 +207,10 @@ export declare function createHarnessClient(config?: HarnessClientConfig): {
      * Update an agent definition.
      */
     updateAgentDefinition(agentId: string, input: HarnessAgentWriteInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Invoke a managed agent definition.
+     */
+    invokeManagedAgentDefinition(agentId: string, input: Omit<HarnessInvokeManagedAgentInput, "agentDefinitionId">, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
     /**
      * List runs for an agent definition.
      */
@@ -167,6 +252,10 @@ export declare function createHarnessClient(config?: HarnessClientConfig): {
      * Update a tool definition.
      */
     updateToolDefinition(toolId: string, input: HarnessToolWriteInput, idempotencyKey?: string): Promise<import("./coreClient").PlatformGatewaySuccess<unknown>>;
+    /**
+     * Execute a tool definition.
+     */
+    executeToolDefinition(toolId: string, input?: HarnessExecuteToolInput): Promise<import("./coreClient").PlatformGatewaySuccess<HarnessExecuteToolResult>>;
     /**
      * List run ledger entries.
      */