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

package/src/harnessClient.ts

@@ -1,585 +0,0 @@
-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",
-      });
-    },
-  };
-}