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

package/src/mcpParitySurface.ts

@@ -0,0 +1,70 @@
+/** Descriptor mapping an MCP tool name to its SDK method path and read/mutation classification. */
+export type McpParityMethod = {
+  toolName: string;
+  methodPath: string;
+  kind: "read" | "mutation";
+};
+
+/** Complete registry of MCP tools with SDK parity, mapping tool names to SDK method paths. */
+export const SDK_MCP_PARITY_METHODS: readonly McpParityMethod[] = [
+  { toolName: "activate_worktree", methodPath: "worktrees.activate", kind: "mutation" },
+  { toolName: "update_worktree_metadata", methodPath: "worktrees.updateMetadata", kind: "mutation" },
+  { toolName: "update_worktree_targets", methodPath: "worktrees.updateTargets", kind: "mutation" },
+  { toolName: "list_all_worktrees", methodPath: "worktrees.listAll", kind: "read" },
+  { toolName: "pipeline_snapshot", methodPath: "worktrees.pipelineSnapshot", kind: "read" },
+  { toolName: "record_scope_learning", methodPath: "context.recordScopeLearning", kind: "mutation" },
+  { toolName: "discover", methodPath: "context.discover", kind: "read" },
+  { toolName: "analyze_topic_density", methodPath: "context.analyzeTopicDensity", kind: "read" },
+  { toolName: "apply_auto_branching", methodPath: "context.applyAutoBranching", kind: "mutation" },
+  { toolName: "seed_belief_lattice", methodPath: "context.seedBeliefLattice", kind: "mutation" },
+  { toolName: "get_lattice_coverage", methodPath: "context.getLatticeCoverage", kind: "read" },
+  { toolName: "match_entity_type", methodPath: "context.matchEntityType", kind: "read" },
+  { toolName: "discover_entity_connections", methodPath: "context.discoverEntityConnections", kind: "read" },
+  { toolName: "trigger_belief_review", methodPath: "context.triggerBeliefReview", kind: "mutation" },
+  { toolName: "list_ontologies", methodPath: "ontologies.list", kind: "read" },
+  { toolName: "get_ontology", methodPath: "ontologies.get", kind: "read" },
+  { toolName: "apply_ontology", methodPath: "ontologies.bind", kind: "mutation" },
+  { toolName: "create_ontology", methodPath: "ontologies.create", kind: "mutation" },
+  { toolName: "update_ontology", methodPath: "ontologies.update", kind: "mutation" },
+  { toolName: "archive_ontology", methodPath: "ontologies.archive", kind: "mutation" },
+  { toolName: "create_ontology_version", methodPath: "ontologies.createVersion", kind: "mutation" },
+  { toolName: "publish_ontology_version", methodPath: "ontologies.publishVersion", kind: "mutation" },
+  { toolName: "deprecate_ontology_version", methodPath: "ontologies.deprecateVersion", kind: "mutation" },
+  { toolName: "resolve_effective_ontology", methodPath: "ontologies.resolveEffective", kind: "read" },
+  { toolName: "register_session", methodPath: "coordination.registerSession", kind: "mutation" },
+  { toolName: "heartbeat_session", methodPath: "coordination.heartbeatSession", kind: "mutation" },
+  { toolName: "end_session", methodPath: "coordination.endSession", kind: "mutation" },
+  { toolName: "list_active_sessions", methodPath: "coordination.listActiveSessions", kind: "read" },
+  { toolName: "send_agent_message", methodPath: "coordination.sendAgentMessage", kind: "mutation" },
+  { toolName: "broadcast_message", methodPath: "coordination.broadcastMessage", kind: "mutation" },
+  { toolName: "get_agent_inbox", methodPath: "coordination.getInbox", kind: "read" },
+  { toolName: "claim_files", methodPath: "coordination.claimFiles", kind: "mutation" },
+  { toolName: "create_topic", methodPath: "topics.create", kind: "mutation" },
+  { toolName: "get_topic", methodPath: "topics.get", kind: "read" },
+  { toolName: "get_topic_tree", methodPath: "topics.getTree", kind: "read" },
+  { toolName: "list_tasks", methodPath: "tasks.list", kind: "read" },
+  { toolName: "create_answer", methodPath: "answers.create", kind: "mutation" },
+  { toolName: "get_answer", methodPath: "answers.get", kind: "read" },
+  { toolName: "flag_contradiction", methodPath: "contradictions.flag", kind: "mutation" },
+  { toolName: "ingest_observation", methodPath: "observations.ingest", kind: "mutation" },
+  { toolName: "get_observation_context", methodPath: "observations.getContext", kind: "read" },
+  { toolName: "get_code_context", methodPath: "coding.getCodeContext", kind: "read" },
+  { toolName: "get_change_history", methodPath: "coding.getChangeHistory", kind: "read" },
+  { toolName: "record_attempt", methodPath: "coding.recordAttempt", kind: "mutation" },
+  { toolName: "get_failure_log", methodPath: "coding.getFailureLog", kind: "read" },
+  { toolName: "create_epistemic_contract", methodPath: "contracts.create", kind: "mutation" },
+  { toolName: "evaluate_contract", methodPath: "contracts.evaluate", kind: "mutation" },
+  { toolName: "get_contract_status", methodPath: "contracts.getStatus", kind: "read" },
+  { toolName: "check_permission", methodPath: "policy.checkPermission", kind: "read" },
+  { toolName: "filter_by_permission", methodPath: "policy.filterByPermission", kind: "read" },
+  { toolName: "manage_write_policy", methodPath: "policy.manageWritePolicy", kind: "mutation" },
+  { toolName: "generate_session_handoff", methodPath: "bootstrap.generateSessionHandoff", kind: "read" },
+];
+
+export const SDK_MCP_PARITY_METHOD_PATHS = SDK_MCP_PARITY_METHODS.map(
+  (entry) => entry.methodPath
+);
+
+export const SDK_MCP_PARITY_TOOL_NAMES = SDK_MCP_PARITY_METHODS.map(
+  (entry) => entry.toolName
+);

package/src/ontologyClient.ts

@@ -0,0 +1,275 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  type GatewayScope,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData } from "./sdkSurface";
+import type { JsonObject } from "./types";
+
+/** Configuration for the ontology client. */
+export type OntologyClientConfig = GatewayClientConfig;
+
+/** Input for binding an ontology to a topic. */
+export type OntologyBindingInput = GatewayScope & {
+  ontologyId: string;
+  topicId: string;
+};
+
+/** Input for creating an ontology definition. */
+export type OntologyDefinitionInput = GatewayScope & {
+  ontologyKey: string;
+  name: string;
+  description?: string;
+  tenantId?: string;
+  tier?: "platform" | "pack" | "tenant";
+};
+
+/** Input for updating mutable fields on an ontology definition. */
+export type OntologyDefinitionUpdateInput = GatewayScope & {
+  name?: string;
+  description?: string;
+  status?: "draft" | "active" | "deprecated";
+};
+
+/** Input for creating a versioned snapshot of entity and edge type definitions. */
+export type OntologyVersionInput = GatewayScope & {
+  version: string;
+  entityTypes: Array<{
+    value: string;
+    label: string;
+    description?: string;
+    schema?: JsonObject;
+    subtypes?: Array<{ value: string; label: string; description?: string }>;
+  }>;
+  edgeTypes: Array<{
+    value: string;
+    label: string;
+    description?: string;
+    sourceTypes?: string[];
+    targetTypes?: string[];
+    constraintSeverity?: "warn" | "info";
+  }>;
+  releaseNotes?: string;
+};
+
+/**
+ * Create the ontology client for ontology definitions and versions.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage ontology definitions, versions, and bindings.
+ */
+export function createOntologyClient(config: OntologyClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List ontology definitions matching optional filters.
+     */
+    async list(
+      filters: GatewayScope & {
+        tenantId?: string;
+        tier?: string;
+        status?: string;
+      } = {}
+    ) {
+      return gateway
+        .request<unknown>({
+          path: `/api/platform/v1/ontologies${toQueryString(filters)}`,
+        })
+        .then((response) =>
+          mapGatewayData(response, (data) => {
+            const record =
+              data && typeof data === "object" && !Array.isArray(data)
+                ? (data as Record<string, unknown>)
+                : {};
+            const ontologies = Array.isArray(record.ontologies)
+              ? record.ontologies
+              : Array.isArray(record.definitions)
+                ? record.definitions
+                : Array.isArray(data)
+                  ? data
+                  : [];
+            const total =
+              typeof record.total === "number" && Number.isFinite(record.total)
+                ? record.total
+                : ontologies.length;
+            return {
+              ...record,
+              ...createListResult(ontologies, "definitions"),
+              ontologies,
+              total,
+            };
+          })
+        );
+    },
+
+    /**
+     * Get an ontology definition by identifier.
+     */
+    async get(id: string) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/ontologies/${encodeURIComponent(id)}`,
+      });
+    },
+
+    /**
+     * Bind an ontology definition to a topic.
+     */
+    async bind(input: OntologyBindingInput, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/ontologies/${encodeURIComponent(input.ontologyId)}/bind`,
+        method: "POST",
+        body: {
+          topicId: input.topicId,
+        },
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List ontology definitions.
+     */
+    async listDefinitions(
+      filters: GatewayScope & {
+        tenantId?: string;
+        tier?: string;
+        status?: string;
+      } = {}
+    ) {
+      return this.list(filters);
+    },
+
+    /**
+     * Get an ontology definition.
+     */
+    async getDefinition(id: string) {
+      return this.get(id);
+    },
+
+    /**
+     * Create an ontology definition.
+     */
+    async createDefinition(
+      input: OntologyDefinitionInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/ontologies",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update an ontology definition.
+     */
+    async updateDefinition(
+      id: string,
+      input: OntologyDefinitionUpdateInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/ontologies/${encodeURIComponent(id)}`,
+        method: "PATCH",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Archive an ontology definition.
+     */
+    async archiveDefinition(id: string, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/ontologies/${encodeURIComponent(id)}`,
+        method: "DELETE",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List versions for an ontology definition.
+     */
+    async listVersions(
+      ontologyId: string,
+      filters: GatewayScope & { status?: string } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/ontologies/${encodeURIComponent(ontologyId)}/versions${toQueryString(filters)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "versions")
+        )
+      );
+    },
+
+    /**
+     * Create an ontology version.
+     */
+    async createVersion(
+      ontologyId: string,
+      input: OntologyVersionInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/ontologies/${encodeURIComponent(ontologyId)}/versions`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Publish an ontology version.
+     */
+    async publishVersion(
+      ontologyId: string,
+      versionId: string,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/ontologies/${encodeURIComponent(ontologyId)}/versions/${encodeURIComponent(versionId)}/publish`,
+        method: "POST",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Deprecate an ontology version.
+     */
+    async deprecateVersion(
+      ontologyId: string,
+      versionId: string,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/ontologies/${encodeURIComponent(ontologyId)}/versions/${encodeURIComponent(versionId)}/deprecate`,
+        method: "POST",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List topics directly bound to a specific ontology definition.
+     * Uses the topics gateway with ontologyId filter.
+     */
+    async listTopics(ontologyId: string) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/topics?ontologyId=${encodeURIComponent(ontologyId)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "topics")
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listTopics.
+     */
+    async listTopicsByOntology(ontologyId: string) {
+      return this.listTopics(ontologyId);
+    },
+  };
+}

package/src/packRuntime.ts

@@ -0,0 +1,3 @@
+// TODO(exfill): restore package-backed pack runtime exports after the legacy
+// STACKOS lib/platform/packs surface is migrated into Lucern packages.
+export {};

package/src/packsClient.ts

@@ -0,0 +1,260 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  type GatewayScope,
+  LucernApiError,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import { createListResult, mapGatewayData } from "./sdkSurface";
+import type { JsonObject } from "./types";
+
+export { LucernApiError };
+export type { GatewayScope, PlatformGatewaySuccess } from "./coreClient";
+
+/** Configuration for the packs client. */
+export type PacksClientConfig = GatewayClientConfig;
+
+/** Input for installing a pack into a tenant or workspace scope. */
+export type PackInstallInput = GatewayScope & {
+  packKey: string;
+  version?: string;
+  autoEnable?: boolean;
+  metadata?: JsonObject;
+};
+
+/** Input for enabling a previously installed pack. */
+export type PackEnableInput = GatewayScope & {
+  packKey: string;
+  metadata?: JsonObject;
+};
+
+/** Input for disabling an active pack. */
+export type PackDisableInput = GatewayScope & {
+  packKey: string;
+  force?: boolean;
+  metadata?: JsonObject;
+};
+
+/** Input for uninstalling a pack from a tenant or workspace scope. */
+export type PackUninstallInput = GatewayScope & {
+  packKey: string;
+  metadata?: JsonObject;
+};
+
+/** Input for upgrading a pack through the prepare/canary/commit/rollback lifecycle. */
+export type PackUpgradeInput = GatewayScope & {
+  packKey: string;
+  mode: "prepare" | "canary" | "commit" | "rollback";
+  targetVersion?: string;
+  metadata?: JsonObject;
+};
+
+/** Input for creating or updating a pack entitlement record. */
+export type PackEntitlementInput = GatewayScope & {
+  packKey: string;
+  status: "active" | "disabled" | "revoked";
+  allowedLifecycles?: Array<"active" | "beta" | "experimental">;
+  minVersion?: string;
+  maxVersion?: string;
+  metadata?: JsonObject;
+};
+
+/**
+ * Create the packs client for pack catalog, state, and entitlement operations.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage pack lifecycle, telemetry, and entitlements.
+ */
+export function createPacksClient(config: PacksClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+
+  return {
+    /**
+     * List catalog entries for available packs.
+     */
+    async listCatalog() {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/packs/catalog",
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "catalog")
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listCatalog.
+     */
+    async getCatalog() {
+      return this.listCatalog();
+    },
+
+    /**
+     * Get the discovery catalog for packs.
+     */
+    async getDiscoveryCatalog() {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/packs/discovery",
+      });
+    },
+
+    /**
+     * Get discovery details for a specific pack.
+     */
+    async getDiscoveryDetail(packKey: string) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/packs/discovery/${encodeURIComponent(packKey)}`,
+      });
+    },
+
+    /**
+     * List pack states for the current scope.
+     */
+    async listStates(query: GatewayScope = {}) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/packs/states${toQueryString(query)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "states")
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listStates.
+     */
+    async getStates(query: GatewayScope = {}) {
+      return this.listStates(query);
+    },
+
+    /**
+     * Get health details for a pack.
+     */
+    async getHealth(packKey: string, query: GatewayScope = {}) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/packs/${encodeURIComponent(packKey)}/health${toQueryString(
+          query
+        )}`,
+      });
+    },
+
+    /**
+     * List pack telemetry entries.
+     */
+    async listTelemetry(
+      query: GatewayScope & { lookbackHours?: number; limit?: number } = {}
+    ) {
+      return gateway.request<unknown>({
+        path: `/api/platform/v1/packs/telemetry${toQueryString(query)}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          createListResult(Array.isArray(data) ? data : [], "telemetry")
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use listTelemetry.
+     */
+    async getTelemetry(
+      query: GatewayScope & { lookbackHours?: number; limit?: number } = {}
+    ) {
+      return this.listTelemetry(query);
+    },
+
+    /**
+     * Create a pack entitlement.
+     */
+    async createEntitlement(
+      input: PackEntitlementInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/packs/entitlements",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a pack entitlement.
+     */
+    async updateEntitlement(
+      input: PackEntitlementInput,
+      idempotencyKey?: string
+    ) {
+      return this.createEntitlement(input, idempotencyKey);
+    },
+
+    /**
+     * @deprecated Use createEntitlement or updateEntitlement.
+     */
+    async upsertEntitlement(
+      input: PackEntitlementInput,
+      idempotencyKey?: string
+    ) {
+      return this.createEntitlement(input, idempotencyKey);
+    },
+
+    /**
+     * Install a pack.
+     */
+    async install(input: PackInstallInput, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/packs/install",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Enable a pack.
+     */
+    async enable(input: PackEnableInput, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/packs/enable",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Disable a pack.
+     */
+    async disable(input: PackDisableInput, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/packs/disable",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Uninstall a pack.
+     */
+    async uninstall(input: PackUninstallInput, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/packs/uninstall",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Upgrade a pack.
+     */
+    async upgrade(input: PackUpgradeInput, idempotencyKey?: string) {
+      return gateway.request<unknown>({
+        path: "/api/platform/v1/packs/upgrade",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+  };
+}