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

package/src/harnessClient.ts

@@ -0,0 +1,585 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  type GatewayScope,
+  LucernApiError,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData, normalizeTopicQuery } from "./sdkSurface";
+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;
+  displayName: string;
+  description: string;
+  version: string;
+  status?: "active" | "deprecated" | "disabled";
+  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;
+  description: string;
+  version: string;
+  status?: "draft" | "active" | "deprecated" | "disabled";
+  executionAdapter:
+    | "convex_mutation"
+    | "convex_action"
+    | "http_callback"
+    | "mcp_tool"
+    | "sdk_invocation"
+    | "external_observed";
+  gateClassification?: "core" | "shimmed";
+  scopeRequirements?: string[];
+  requiredRole?: string;
+  requiredAction?: string;
+  surfaces?: string[];
+  category?: string;
+  parameterSchema?: JsonObject;
+  returnSchema?: JsonObject;
+  handlerRef?: string;
+  callbackUrl?: string;
+  safetyMetadata: {
+    readOnly?: boolean;
+    idempotent?: boolean;
+    sideEffectLevel: "none" | "low" | "high";
+  };
+  exampleInvocations?: Array<{
+    input: JsonObject;
+    expectedOutput?: JsonValue;
+  }>;
+  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;
+  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";
+  metadata?: JsonObject;
+  toolCallId?: string;
+  toolName?: string;
+  executionAdapter?:
+    | "convex_mutation"
+    | "convex_action"
+    | "http_callback"
+    | "mcp_tool"
+    | "sdk_invocation"
+    | "external_observed";
+  policyDecisionId?: string;
+  requiredScopes?: string[];
+  policyResult?: "allowed" | "denied";
+  policyReasonCode?: string;
+  inputHash?: string;
+  outputHash?: string;
+  durationMs?: number;
+  success?: boolean;
+  startedAt?: number;
+  completedAt?: number;
+  input?: JsonObject;
+  result?: JsonValue;
+  promptKey?: string;
+  promptVersion?: string;
+  decision?: string;
+  reasonCode?: string;
+  latencyMs?: number;
+  error?:
+    | string
+    | {
+        code?: string;
+        message: string;
+        details?: JsonValue;
+      };
+};
+
+/** Input for completing a harness run with a terminal status. */
+export type HarnessCompleteRunInput = {
+  reportingToken: string;
+  status: "completed" | "failed" | "timeout";
+  error?: {
+    category:
+      | "policy_denied"
+      | "tool_execution"
+      | "prompt_resolution"
+      | "model_error"
+      | "timeout"
+      | "heartbeat_timeout"
+      | "input_validation"
+      | "internal"
+      | "external_service";
+    message: string;
+    code?: string;
+  };
+};
+
+/**
+ * Create the harness client for agent and tool registry operations.
+ */
+export function createHarnessClient(config: HarnessClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List agent definitions.
+     */
+    async listAgentDefinitions(
+      scope: GatewayScope & {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/agents${toQueryString(scope)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "agents")
+        )
+      );
+    },
+
+    /**
+     * Get an agent definition.
+     */
+    async getAgentDefinition(agentId: string, scope: GatewayScope = {}) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/agents/${encodeURIComponent(agentId)}${toQueryString(scope)}`,
+      });
+    },
+
+    /**
+     * Create an agent definition.
+     */
+    async createAgentDefinition(
+      input: HarnessAgentWriteInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/harness/agents",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * @deprecated Use createAgentDefinition.
+     */
+    async registerAgentDefinition(
+      input: HarnessAgentWriteInput,
+      idempotencyKey?: string
+    ) {
+      return this.createAgentDefinition(input, idempotencyKey);
+    },
+
+    /**
+     * Update an agent definition.
+     */
+    async updateAgentDefinition(
+      agentId: string,
+      input: HarnessAgentWriteInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/agents/${encodeURIComponent(agentId)}`,
+        method: "PUT",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Invoke a managed agent definition.
+     */
+    async invokeManagedAgentDefinition(
+      agentId: string,
+      input: Omit<HarnessInvokeManagedAgentInput, "agentDefinitionId">,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/agents/${encodeURIComponent(agentId)}/runs`,
+        method: "POST",
+        body: {
+          agentDefinitionId: agentId,
+          ...input,
+        },
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List runs for an agent definition.
+     */
+    async listAgentRuns(
+      agentId: string,
+      scope: GatewayScope & {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/agents/${encodeURIComponent(agentId)}/runs${toQueryString(scope)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "runs")
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listAgentRuns.
+     */
+    async listRunsForAgent(
+      agentId: string,
+      scope: GatewayScope & {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+      } = {}
+    ) {
+      return this.listAgentRuns(agentId, scope);
+    },
+
+    /**
+     * List tool definitions.
+     */
+    async listToolDefinitions(
+      scope: GatewayScope & {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+        gateClassification?: string;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/tools${toQueryString(scope)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "tools")
+        )
+      );
+    },
+
+    /**
+     * Get a tool definition.
+     */
+    async getToolDefinition(toolId: string, scope: GatewayScope = {}) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/tools/${encodeURIComponent(toolId)}${toQueryString(scope)}`,
+      });
+    },
+
+    /**
+     * Create a tool definition.
+     */
+    async createToolDefinition(
+      input: HarnessToolWriteInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/harness/tools",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * @deprecated Use createToolDefinition.
+     */
+    async registerToolDefinition(
+      input: HarnessToolWriteInput,
+      idempotencyKey?: string
+    ) {
+      return this.createToolDefinition(input, idempotencyKey);
+    },
+
+    /**
+     * Update a tool definition.
+     */
+    async updateToolDefinition(
+      toolId: string,
+      input: HarnessToolWriteInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/tools/${encodeURIComponent(toolId)}`,
+        method: "PUT",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Execute a tool definition.
+     */
+    async executeToolDefinition(
+      toolId: string,
+      input: HarnessExecuteToolInput = {}
+    ) {
+      return gateway.request<HarnessExecuteToolResult>({
+        path: `/api/platform/v1/harness/tools/${encodeURIComponent(toolId)}/execute`,
+        method: "POST",
+        body: input,
+      });
+    },
+
+    /**
+     * List run ledger entries.
+     */
+    async listRunEntries(
+      scope: GatewayScope & {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+      } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/runs${toQueryString(scope)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "runs")
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listRunEntries.
+     */
+    async listRunLedgerEntries(
+      scope: GatewayScope & {
+        status?: string;
+        limit?: number;
+        cursor?: string;
+      } = {}
+    ) {
+      return this.listRunEntries(scope);
+    },
+
+    /**
+     * Create a harness run.
+     */
+    async startHarnessRun(
+      input: HarnessStartRunInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/harness/runs",
+        method: "POST",
+        body: normalizeTopicQuery(input),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Get a run ledger entry.
+     */
+    async getRunLedgerEntry(runId: string) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/runs/${encodeURIComponent(runId)}`,
+      });
+    },
+
+    /**
+     * Update a harness run with a ledger event.
+     */
+    async reportHarnessRunEvent(
+      runId: string,
+      input: HarnessRunReportInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/runs/${encodeURIComponent(runId)}/report`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a harness run heartbeat.
+     */
+    async heartbeatHarnessRun(
+      runId: string,
+      input: { reportingToken: string },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/runs/${encodeURIComponent(runId)}/heartbeat`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Complete a harness run.
+     */
+    async completeHarnessRun(
+      runId: string,
+      input: HarnessCompleteRunInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/runs/${encodeURIComponent(runId)}/complete`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List prompt resolutions.
+     */
+    async listPromptResolutions(
+      query: { runId?: string; promptName?: string; limit?: number } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/harness/prompts${toQueryString(query)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "prompts")
+        )
+      );
+    },
+
+    /**
+     * Get the harness scope taxonomy.
+     */
+    async getScopeTaxonomy() {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/harness/scopes",
+      });
+    },
+  };
+}