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

package/src/customTools.ts

@@ -1,398 +0,0 @@
-import { z } from "zod";
-import type {
-  McpParameterDef,
-  McpResponseDef,
-  McpToolContract,
-} from "./contracts/mcpTools";
-import type { JsonObject } from "./types";
-
-/** Default namespace assigned to custom tools when none is specified. */
-const DEFAULT_CUSTOM_NAMESPACE = "custom";
-
-/** Namespace strings reserved for platform-internal tools. */
-const RESERVED_NAMESPACES = new Set(["lucern"]);
-
-type AnyZodObject = z.ZodObject<z.ZodRawShape>;
-
-/** Origin of a custom tool invocation (SDK call or MCP request). */
-export type CustomToolInvocationSource = "sdk" | "mcp";
-
-/** Runtime context passed to a custom tool handler during invocation. */
-export type CustomToolInvocationContext = {
-  source: CustomToolInvocationSource;
-};
-
-/** Optional metadata attached to a custom tool registration. */
-export type CustomToolMetadata = {
-  category?: string;
-  tags?: string[];
-  requiredScopes?: string[];
-};
-
-/** Input descriptor for registering a custom tool with its schemas and handler. */
-export type CustomToolRegistration<
-  TInput extends AnyZodObject = AnyZodObject,
-  TOutput extends z.ZodTypeAny = z.ZodTypeAny,
-> = {
-  namespace?: string;
-  name: string;
-  description: string;
-  inputSchema: TInput;
-  outputSchema: TOutput;
-  handler: (
-    input: z.infer<TInput>,
-    context: CustomToolInvocationContext
-  ) => Promise<z.infer<TOutput>> | z.infer<TOutput>;
-  metadata?: CustomToolMetadata;
-  ownerModule?: string;
-  ontologyPrimitive?: McpToolContract["ontologyPrimitive"];
-  tier?: McpToolContract["tier"];
-};
-
-/** A fully resolved custom tool entry stored in the in-memory registry. */
-export type RegisteredCustomTool = {
-  fullName: string;
-  namespace: string;
-  shortName: string;
-  metadata: CustomToolMetadata;
-  contract: McpToolContract;
-  inputSchema: AnyZodObject;
-  outputSchema: z.ZodTypeAny;
-  invoke: (
-    input: JsonObject,
-    context: CustomToolInvocationContext
-  ) => Promise<unknown>;
-};
-
-/** Error thrown when custom tool registration or invocation fails validation. */
-export class CustomToolRegistryError extends Error {
-  constructor(message: string) {
-    super(message);
-    this.name = "CustomToolRegistryError";
-  }
-}
-
-const customToolRegistry = new Map<string, RegisteredCustomTool>();
-
-function normalizeSegment(value: string, field: "namespace" | "name"): string {
-  const normalized = value.trim();
-  if (!normalized) {
-    throw new CustomToolRegistryError(`Custom tool ${field} is required.`);
-  }
-  if (!/^[a-zA-Z][a-zA-Z0-9_-]*$/.test(normalized)) {
-    throw new CustomToolRegistryError(
-      `Invalid custom tool ${field}: "${value}". Use letters, numbers, "_" or "-".`
-    );
-  }
-  return normalized;
-}
-
-function normalizeNamespace(namespace?: string): string {
-  const resolved = normalizeSegment(
-    namespace ?? DEFAULT_CUSTOM_NAMESPACE,
-    "namespace"
-  );
-  if (RESERVED_NAMESPACES.has(resolved.toLowerCase())) {
-    throw new CustomToolRegistryError(
-      `Namespace "${resolved}" is reserved for platform tools.`
-    );
-  }
-  return resolved;
-}
-
-function normalizeName(name: string): string {
-  if (name.includes(".")) {
-    throw new CustomToolRegistryError(
-      `Custom tool name "${name}" must not include "."; use namespace + name.`
-    );
-  }
-  return normalizeSegment(name, "name");
-}
-
-function buildFullName(namespace: string, shortName: string): string {
-  return `${namespace}.${shortName}`;
-}
-
-function unwrapSchema(schema: z.ZodTypeAny): {
-  schema: z.ZodTypeAny;
-  required: boolean;
-} {
-  if (schema instanceof z.ZodOptional) {
-    return { schema: schema.unwrap(), required: false };
-  }
-  if (schema instanceof z.ZodDefault) {
-    const removeDefault = (
-      schema as unknown as { removeDefault?: () => z.ZodTypeAny }
-    ).removeDefault;
-    if (typeof removeDefault === "function") {
-      return { schema: removeDefault.call(schema), required: false };
-    }
-    const inner = (schema as unknown as { _def?: { innerType?: z.ZodTypeAny } })
-      ._def?.innerType;
-    return { schema: inner ?? schema, required: false };
-  }
-  return { schema, required: true };
-}
-
-function resolveParameterType(schema: z.ZodTypeAny): {
-  type: McpParameterDef["type"];
-  enum?: string[];
-} {
-  if (schema instanceof z.ZodString) {
-    return { type: "string" };
-  }
-  if (schema instanceof z.ZodEnum) {
-    return { type: "string", enum: schema.options };
-  }
-  if (schema instanceof z.ZodNativeEnum) {
-    const values = Object.values(schema.enum).filter(
-      (value): value is string => typeof value === "string"
-    );
-    return values.length > 0
-      ? { type: "string", enum: values }
-      : { type: "string" };
-  }
-  if (schema instanceof z.ZodLiteral) {
-    const literalValue = schema.value;
-    if (typeof literalValue === "string") {
-      return { type: "string", enum: [literalValue] };
-    }
-    if (typeof literalValue === "number") {
-      return { type: "number" };
-    }
-    if (typeof literalValue === "boolean") {
-      return { type: "boolean" };
-    }
-    return { type: "object" };
-  }
-  if (schema instanceof z.ZodNumber) {
-    return { type: "number" };
-  }
-  if (schema instanceof z.ZodBoolean) {
-    return { type: "boolean" };
-  }
-  if (schema instanceof z.ZodArray) {
-    return { type: "array" };
-  }
-  return { type: "object" };
-}
-
-function schemaTypeLabel(schema: z.ZodTypeAny): string {
-  if (schema instanceof z.ZodString || schema instanceof z.ZodEnum) {
-    return "string";
-  }
-  if (schema instanceof z.ZodNumber) {
-    return "number";
-  }
-  if (schema instanceof z.ZodBoolean) {
-    return "boolean";
-  }
-  if (schema instanceof z.ZodArray) {
-    return "array";
-  }
-  if (schema instanceof z.ZodObject) {
-    return "object";
-  }
-  return "unknown";
-}
-
-function parseObjectSchema<TInput extends AnyZodObject>(
-  value: TInput,
-  fieldName: string
-): TInput {
-  if (!(value instanceof z.ZodObject)) {
-    throw new CustomToolRegistryError(
-      `${fieldName} must be a Zod object schema.`
-    );
-  }
-  return value;
-}
-
-function deriveParameters(schema: AnyZodObject): {
-  parameters: Record<string, McpParameterDef>;
-  required: string[];
-} {
-  const shape = schema.shape;
-  const parameters: Record<string, McpParameterDef> = {};
-  const required: string[] = [];
-
-  for (const [key, raw] of Object.entries(shape)) {
-    const { schema: unwrapped, required: isRequired } = unwrapSchema(
-      raw as z.ZodTypeAny
-    );
-    const parameterType = resolveParameterType(unwrapped);
-    parameters[key] = {
-      type: parameterType.type,
-      description: (raw as z.ZodTypeAny).description ?? `${key} parameter`,
-      ...(parameterType.enum ? { enum: parameterType.enum } : {}),
-    };
-    if (isRequired) {
-      required.push(key);
-    }
-  }
-
-  return { parameters, required };
-}
-
-function deriveResponse(schema: z.ZodTypeAny): McpResponseDef {
-  if (schema instanceof z.ZodObject) {
-    const fields = Object.fromEntries(
-      Object.entries(schema.shape).map(([key, value]) => {
-        const zodValue = value as z.ZodTypeAny;
-        const label = schemaTypeLabel(unwrapSchema(zodValue).schema);
-        const description = zodValue.description ?? "custom output field";
-        return [key, `${label} — ${description}`];
-      })
-    );
-    return {
-      description: "Custom tool result payload",
-      fields,
-    };
-  }
-
-  return {
-    description: "Custom tool result payload",
-    fields: {
-      result: `${schemaTypeLabel(schema)} — custom output payload`,
-    },
-  };
-}
-
-function buildContract<
-  TInput extends AnyZodObject,
-  TOutput extends z.ZodTypeAny,
->(
-  fullName: string,
-  namespace: string,
-  registration: CustomToolRegistration<TInput, TOutput>,
-  inputSchema: TInput
-): McpToolContract {
-  const { parameters, required } = deriveParameters(inputSchema);
-  return {
-    name: fullName,
-    description: registration.description,
-    parameters,
-    required,
-    response: deriveResponse(registration.outputSchema),
-    ownerModule: registration.ownerModule ?? `${namespace}-extension`,
-    ontologyPrimitive: registration.ontologyPrimitive ?? "task",
-    tier: registration.tier ?? "workhorse",
-  };
-}
-
-/**
- * Register a custom SDK tool in the in-memory registry.
- * @param registration - The tool definition including name, schemas, and handler.
- * @param options - Optional flags; set `replace` to overwrite an existing registration.
- * @returns The fully resolved registered tool entry.
- */
-export function registerCustomTool<
-  TInput extends AnyZodObject,
-  TOutput extends z.ZodTypeAny,
->(
-  registration: CustomToolRegistration<TInput, TOutput>,
-  options: { replace?: boolean } = {}
-): RegisteredCustomTool {
-  const namespace = normalizeNamespace(registration.namespace);
-  const shortName = normalizeName(registration.name);
-  const fullName = buildFullName(namespace, shortName);
-
-  if (customToolRegistry.has(fullName) && !options.replace) {
-    throw new CustomToolRegistryError(
-      `Custom tool "${fullName}" is already registered.`
-    );
-  }
-
-  const inputSchema = parseObjectSchema(
-    registration.inputSchema,
-    "inputSchema"
-  );
-  const outputSchema = registration.outputSchema;
-  const contract = buildContract(
-    fullName,
-    namespace,
-    registration,
-    inputSchema
-  );
-  const metadata: CustomToolMetadata = {
-    category: registration.metadata?.category,
-    tags: registration.metadata?.tags ?? [],
-    requiredScopes: registration.metadata?.requiredScopes ?? ["custom:execute"],
-  };
-
-  const registered: RegisteredCustomTool = {
-    fullName,
-    namespace,
-    shortName,
-    metadata,
-    contract,
-    inputSchema,
-    outputSchema,
-    invoke: async (input, context) => {
-      const parsedInput = inputSchema.parse(input);
-      const rawOutput = await registration.handler(parsedInput, context);
-      return outputSchema.parse(rawOutput);
-    },
-  };
-
-  customToolRegistry.set(fullName, registered);
-  return registered;
-}
-
-/**
- * Remove a custom SDK tool from the registry.
- * @param fullName - Fully qualified tool name (`namespace.name`).
- * @returns `true` if the tool was found and removed, `false` otherwise.
- */
-export function unregisterCustomTool(fullName: string): boolean {
-  return customToolRegistry.delete(fullName.trim());
-}
-
-/**
- * Get a custom SDK tool by fully qualified name.
- * @param fullName - Fully qualified tool name (`namespace.name`).
- * @returns The registered tool entry, or `undefined` if not found.
- */
-export function getRegisteredCustomTool(
-  fullName: string
-): RegisteredCustomTool | undefined {
-  return customToolRegistry.get(fullName.trim());
-}
-
-/**
- * List all registered custom SDK tools, sorted alphabetically by full name.
- * @returns An array of all registered tool entries.
- */
-export function listRegisteredCustomTools(): RegisteredCustomTool[] {
-  return [...customToolRegistry.values()].sort((left, right) =>
-    left.fullName.localeCompare(right.fullName)
-  );
-}
-
-/**
- * Clear the registered custom tool registry.
- */
-export function clearRegisteredCustomTools(): void {
-  customToolRegistry.clear();
-}
-
-/**
- * Invoke a registered custom SDK tool by fully qualified name.
- * @param fullName - Fully qualified tool name (`namespace.name`).
- * @param params - JSON-serializable input parameters for the tool handler.
- * @param context - Invocation context indicating the call source.
- * @returns The validated output from the tool handler.
- */
-export async function invokeRegisteredCustomTool(
-  fullName: string,
-  params: JsonObject,
-  context: CustomToolInvocationContext
-): Promise<unknown> {
-  const registered = getRegisteredCustomTool(fullName);
-  if (!registered) {
-    throw new CustomToolRegistryError(
-      `Custom tool "${fullName}" is not registered.`
-    );
-  }
-  return registered.invoke(params, context);
-}

package/src/decisionsClient.ts

@@ -1,286 +0,0 @@
-import {
-  createGatewayRequestClient,
-  type GatewayClientConfig,
-  LucernApiError,
-  randomIdempotencyKey,
-  toQueryString,
-} from "./coreClient";
-import {
-  createListResult,
-  mapGatewayData,
-  normalizeTopicQuery,
-  withTopicAlias,
-} from "./sdkSurface";
-import type {
-  GetJudgmentResponse,
-  JudgmentCalibrationResponse,
-  JudgmentRecord,
-  JudgmentReadinessResponse,
-  JudgmentTransitionAuditIntegrityResponse,
-  ListJudgmentsResponse,
-  PendingJudgmentOutcomeReviewResponse,
-  PendingJudgmentOutcomeRecord,
-  RecordJudgmentOutcomeResponse,
-  RecordJudgmentResponse,
-  TopicIdentifierInput,
-} from "./types";
-
-export { LucernApiError };
-export type { PlatformGatewaySuccess } from "./coreClient";
-export type {
-  GetJudgmentResponse,
-  JudgmentCalibrationResponse,
-  JudgmentReadinessResponse,
-  JudgmentTransitionAuditIntegrityResponse,
-  ListJudgmentsResponse,
-  PendingJudgmentOutcomeReviewResponse,
-  RecordJudgmentOutcomeResponse,
-  RecordJudgmentResponse,
-} from "./types";
-
-/** Configuration for the decisions client. */
-export type DecisionsClientConfig = GatewayClientConfig;
-
-/** Input for recording a new judgment (irreversible decision commitment). */
-export type RecordJudgmentInput = {
-  title: string;
-  summary?: string;
-  rationale: string;
-  topicId?: string;
-  confidence?: number;
-  decisionConfidence?: number;
-  judgmentType?: string;
-  decisionType?: string;
-  beliefIds?: string[];
-  keyUncertainties?: string[];
-  alternativesConsidered?: string[];
-  decisionMakers?: string[];
-  companyId?: string;
-  amount?: number;
-  valuation?: number;
-  terms?: string;
-  themeIds?: string[];
-} & TopicIdentifierInput;
-
-/** Filter parameters for listing judgments within a topic scope. */
-export type ListJudgmentsInput = {
-  topicId?: string;
-  includeArchived?: boolean;
-  limit?: number;
-} & TopicIdentifierInput;
-
-/** Input for recording the real-world outcome of a judgment. */
-export type RecordJudgmentOutcomeInput = {
-  outcome:
-    | "pending"
-    | "successful"
-    | "unsuccessful"
-    | "mixed"
-    | "unknown"
-    | "too_early";
-  outcomeNotes?: string;
-  notes?: string;
-};
-
-/** Input for retrieving judgment calibration analytics. */
-export type GetJudgmentCalibrationInput = {
-  topicId?: string;
-} & TopicIdentifierInput;
-
-/** Input for listing judgments still awaiting outcome review. */
-export type ListPendingJudgmentOutcomeReviewInput = {
-  topicId?: string;
-} & TopicIdentifierInput;
-
-/** Input for checking audit integrity of judgment state transitions. */
-export type GetJudgmentTransitionAuditIntegrityInput = {
-  topicId?: string;
-  judgmentId?: string;
-  includePassing?: boolean;
-} & TopicIdentifierInput;
-
-/**
- * Create the judgments client for decision lifecycle operations.
- * @param config - Gateway transport configuration.
- * @returns An object with methods to manage judgments, outcomes, readiness, and calibration.
- */
-export function createDecisionsClient(config: DecisionsClientConfig = {}) {
-  const gateway = createGatewayRequestClient(config);
-
-  return {
-    /**
-     * List judgments for a topic scope.
-     */
-    async listJudgments(query: ListJudgmentsInput) {
-      return gateway.request<ListJudgmentsResponse>({
-        path: `/api/platform/v1/graph/judgments${toQueryString({
-          ...normalizeTopicQuery(query),
-          includeArchived:
-            typeof query.includeArchived === "boolean"
-              ? query.includeArchived
-                ? "true"
-                : "false"
-              : undefined,
-          limit: query.limit,
-        })}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) => {
-          const rows = Array.isArray(data) ? data : [];
-          const judgments = rows.map((row) =>
-            withTopicAlias(row as Record<string, unknown>) as JudgmentRecord
-          );
-          return {
-            ...createListResult(judgments, "judgments"),
-          } as ListJudgmentsResponse;
-        })
-      );
-    },
-
-    /**
-     * Get a single judgment by identifier.
-     */
-    async getJudgment(judgmentId: string) {
-      return gateway.request<GetJudgmentResponse>({
-        path: `/api/platform/v1/graph/judgments/${encodeURIComponent(judgmentId)}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          data && typeof data === "object"
-            ? (withTopicAlias(
-                data as Record<string, unknown>
-              ) as GetJudgmentResponse)
-            : data
-        )
-      );
-    },
-
-    /**
-     * Get readiness signals for creating a judgment.
-     */
-    async getJudgmentReadiness(query: {
-      topicId?: string;
-    } & TopicIdentifierInput) {
-      return gateway.request<JudgmentReadinessResponse>({
-        path: `/api/platform/v1/graph/judgments/readiness${toQueryString(
-          normalizeTopicQuery(query)
-        )}`,
-      });
-    },
-
-    /**
-     * Get calibration analytics for judgment outcomes.
-     */
-    async getJudgmentCalibration(query: GetJudgmentCalibrationInput) {
-      return gateway.request<JudgmentCalibrationResponse>({
-        path: `/api/platform/v1/graph/judgments/calibration${toQueryString(
-          normalizeTopicQuery(query)
-        )}`,
-      });
-    },
-
-    /**
-     * List judgments still awaiting outcome review.
-     */
-    async listPendingOutcomeReviews(
-      query: ListPendingJudgmentOutcomeReviewInput
-    ) {
-      return gateway.request<PendingJudgmentOutcomeReviewResponse>({
-        path: `/api/platform/v1/graph/judgments/pending-outcome-review${toQueryString(
-          normalizeTopicQuery(query)
-        )}`,
-      }).then((response) =>
-        mapGatewayData(response, (data) => {
-          const rows = Array.isArray(data) ? data : [];
-          const reviews = rows.map((row) =>
-            withTopicAlias(
-              row as Record<string, unknown>
-            ) as PendingJudgmentOutcomeRecord
-          );
-          return createListResult(reviews, "reviews");
-        })
-      );
-    },
-
-    /**
-     * @deprecated Use listPendingOutcomeReviews.
-     */
-    async listPendingJudgmentOutcomeReview(
-      query: ListPendingJudgmentOutcomeReviewInput
-    ) {
-      return this.listPendingOutcomeReviews(query);
-    },
-
-    /**
-     * Get audit integrity checks for judgment transitions.
-     */
-    async getJudgmentTransitionAuditIntegrity(
-      query: GetJudgmentTransitionAuditIntegrityInput
-    ) {
-      return gateway.request<JudgmentTransitionAuditIntegrityResponse>({
-        path: `/api/platform/v1/graph/judgments/transition-audit-integrity${toQueryString(
-          {
-            ...normalizeTopicQuery(query),
-            judgmentId: query.judgmentId,
-            includePassing:
-              typeof query.includePassing === "boolean"
-                ? query.includePassing
-                  ? "true"
-                  : "false"
-                : undefined,
-          }
-        )}`,
-      });
-    },
-
-    /**
-     * Create a judgment.
-     */
-    async createJudgment(input: RecordJudgmentInput, idempotencyKey?: string) {
-      return gateway.request<RecordJudgmentResponse>({
-        path: "/api/platform/v1/graph/judgments",
-        method: "POST",
-        body: normalizeTopicQuery(input),
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      }).then((response) =>
-        mapGatewayData(response, (data) =>
-          withTopicAlias(
-            data as Record<string, unknown>
-          ) as RecordJudgmentResponse
-        )
-      );
-    },
-
-    /**
-     * @deprecated Use createJudgment.
-     */
-    async recordJudgment(input: RecordJudgmentInput, idempotencyKey?: string) {
-      return this.createJudgment(input, idempotencyKey);
-    },
-
-    /**
-     * Update the outcome for an existing judgment.
-     */
-    async updateJudgmentOutcome(
-      judgmentId: string,
-      input: RecordJudgmentOutcomeInput,
-      idempotencyKey?: string
-    ) {
-      return gateway.request<RecordJudgmentOutcomeResponse>({
-        path: `/api/platform/v1/graph/judgments/${encodeURIComponent(judgmentId)}/outcome`,
-        method: "POST",
-        body: input,
-        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-      });
-    },
-
-    /**
-     * @deprecated Use updateJudgmentOutcome.
-     */
-    async recordJudgmentOutcome(
-      judgmentId: string,
-      input: RecordJudgmentOutcomeInput,
-      idempotencyKey?: string
-    ) {
-      return this.updateJudgmentOutcome(judgmentId, input, idempotencyKey);
-    },
-  };
-}

package/src/domainContext.ts

@@ -1,15 +0,0 @@
-export type {
-  CompileContextInput,
-  ContextCompilationMode,
-  ContextPackSectionKey,
-  ContextRankingProfile,
-  PackWeightOverride,
-  PublicCompiledContext,
-  PublicContextBelief,
-  PublicContextContradiction,
-  PublicContextEntity,
-  PublicContextEvidence,
-  PublicContextInjectionPolicy,
-  PublicContextQuestion,
-  RankingWeightVector,
-} from "./contextTypes";