@lucern/sdk 0.2.0-alpha.6 → 0.2.0-alpha.8

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

@@ -1,247 +0,0 @@
-import { z } from "zod";
-/** 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"]);
-/** Error thrown when custom tool registration or invocation fails validation. */
-export class CustomToolRegistryError extends Error {
-    constructor(message) {
-        super(message);
-        this.name = "CustomToolRegistryError";
-    }
-}
-const customToolRegistry = new Map();
-function normalizeSegment(value, field) {
-    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) {
-    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) {
-    if (name.includes(".")) {
-        throw new CustomToolRegistryError(`Custom tool name "${name}" must not include "."; use namespace + name.`);
-    }
-    return normalizeSegment(name, "name");
-}
-function buildFullName(namespace, shortName) {
-    return `${namespace}.${shortName}`;
-}
-function unwrapSchema(schema) {
-    if (schema instanceof z.ZodOptional) {
-        return { schema: schema.unwrap(), required: false };
-    }
-    if (schema instanceof z.ZodDefault) {
-        const removeDefault = schema.removeDefault;
-        if (typeof removeDefault === "function") {
-            return { schema: removeDefault.call(schema), required: false };
-        }
-        const inner = schema
-            ._def?.innerType;
-        return { schema: inner ?? schema, required: false };
-    }
-    return { schema, required: true };
-}
-function resolveParameterType(schema) {
-    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) => 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) {
-    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(value, fieldName) {
-    if (!(value instanceof z.ZodObject)) {
-        throw new CustomToolRegistryError(`${fieldName} must be a Zod object schema.`);
-    }
-    return value;
-}
-function deriveParameters(schema) {
-    const shape = schema.shape;
-    const parameters = {};
-    const required = [];
-    for (const [key, raw] of Object.entries(shape)) {
-        const { schema: unwrapped, required: isRequired } = unwrapSchema(raw);
-        const parameterType = resolveParameterType(unwrapped);
-        parameters[key] = {
-            type: parameterType.type,
-            description: raw.description ?? `${key} parameter`,
-            ...(parameterType.enum ? { enum: parameterType.enum } : {}),
-        };
-        if (isRequired) {
-            required.push(key);
-        }
-    }
-    return { parameters, required };
-}
-function deriveResponse(schema) {
-    if (schema instanceof z.ZodObject) {
-        const fields = Object.fromEntries(Object.entries(schema.shape).map(([key, value]) => {
-            const zodValue = value;
-            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(fullName, namespace, registration, inputSchema) {
-    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(registration, options = {}) {
-    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 = {
-        category: registration.metadata?.category,
-        tags: registration.metadata?.tags ?? [],
-        requiredScopes: registration.metadata?.requiredScopes ?? ["custom:execute"],
-    };
-    const registered = {
-        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) {
-    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) {
-    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() {
-    return [...customToolRegistry.values()].sort((left, right) => left.fullName.localeCompare(right.fullName));
-}
-/**
- * Clear the registered custom tool registry.
- */
-export function clearRegisteredCustomTools() {
-    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, params, context) {
-    const registered = getRegisteredCustomTool(fullName);
-    if (!registered) {
-        throw new CustomToolRegistryError(`Custom tool "${fullName}" is not registered.`);
-    }
-    return registered.invoke(params, context);
-}

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

@@ -1,129 +0,0 @@
-import { createGatewayRequestClient, LucernApiError, randomIdempotencyKey, toQueryString, } from "./coreClient.js";
-import { createListResult, mapGatewayData, normalizeTopicQuery, withTopicAlias, } from "./sdkSurface.js";
-export { LucernApiError };
-/**
- * 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 = {}) {
-    const gateway = createGatewayRequestClient(config);
-    return {
-        /**
-         * List judgments for a topic scope.
-         */
-        async listJudgments(query) {
-            return gateway.request({
-                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));
-                return {
-                    ...createListResult(judgments, "judgments"),
-                };
-            }));
-        },
-        /**
-         * Get a single judgment by identifier.
-         */
-        async getJudgment(judgmentId) {
-            return gateway.request({
-                path: `/api/platform/v1/graph/judgments/${encodeURIComponent(judgmentId)}`,
-            }).then((response) => mapGatewayData(response, (data) => data && typeof data === "object"
-                ? withTopicAlias(data)
-                : data));
-        },
-        /**
-         * Get readiness signals for creating a judgment.
-         */
-        async getJudgmentReadiness(query) {
-            return gateway.request({
-                path: `/api/platform/v1/graph/judgments/readiness${toQueryString(normalizeTopicQuery(query))}`,
-            });
-        },
-        /**
-         * Get calibration analytics for judgment outcomes.
-         */
-        async getJudgmentCalibration(query) {
-            return gateway.request({
-                path: `/api/platform/v1/graph/judgments/calibration${toQueryString(normalizeTopicQuery(query))}`,
-            });
-        },
-        /**
-         * List judgments still awaiting outcome review.
-         */
-        async listPendingOutcomeReviews(query) {
-            return gateway.request({
-                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));
-                return createListResult(reviews, "reviews");
-            }));
-        },
-        /**
-         * @deprecated Use listPendingOutcomeReviews.
-         */
-        async listPendingJudgmentOutcomeReview(query) {
-            return this.listPendingOutcomeReviews(query);
-        },
-        /**
-         * Get audit integrity checks for judgment transitions.
-         */
-        async getJudgmentTransitionAuditIntegrity(query) {
-            return gateway.request({
-                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, idempotencyKey) {
-            return gateway.request({
-                path: "/api/platform/v1/graph/judgments",
-                method: "POST",
-                body: normalizeTopicQuery(input),
-                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-            }).then((response) => mapGatewayData(response, (data) => withTopicAlias(data)));
-        },
-        /**
-         * @deprecated Use createJudgment.
-         */
-        async recordJudgment(input, idempotencyKey) {
-            return this.createJudgment(input, idempotencyKey);
-        },
-        /**
-         * Update the outcome for an existing judgment.
-         */
-        async updateJudgmentOutcome(judgmentId, input, idempotencyKey) {
-            return gateway.request({
-                path: `/api/platform/v1/graph/judgments/${encodeURIComponent(judgmentId)}/outcome`,
-                method: "POST",
-                body: input,
-                idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
-            });
-        },
-        /**
-         * @deprecated Use updateJudgmentOutcome.
-         */
-        async recordJudgmentOutcome(judgmentId, input, idempotencyKey) {
-            return this.updateJudgmentOutcome(judgmentId, input, idempotencyKey);
-        },
-    };
-}

package/dist/lib/platform/sdk/domainContext.d.ts

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

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

@@ -1 +0,0 @@
-export {};

package/dist/lib/platform/sdk/events.d.ts

@@ -1,176 +0,0 @@
-export declare const DOMAIN_EVENT_VERSION: "1.0";
-export declare const EVENT_RETENTION_DEFAULT_DAYS = 30;
-export declare const WEBHOOK_MAX_ATTEMPTS = 5;
-export declare const WEBHOOK_RETRY_DELAYS_MS: readonly [1000, 5000, 30000, 300000];
-export declare const DOMAIN_EVENT_TYPES: readonly ["belief.created", "belief.forked", "belief.confidence_updated", "belief.archived", "belief.refined", "belief.contract_created", "belief.contract_evaluated", "belief.lineage_queried", "evidence.created", "evidence.linked", "evidence.search_executed", "question.created", "question.answered", "question.refined", "question.status_updated", "question.archived", "edge.created", "contradiction.flagged", "worktree.created", "worktree.activated", "worktree.merged", "worktree.targets_updated", "worktree.metadata_updated", "topic.created", "topic.updated", "topic.archived", "task.created", "task.completed", "task.updated", "ontology.bound", "context.compiled", "identity.key_created", "identity.key_rotated", "identity.key_revoked", "webhook.test"];
-export type DomainEventType = (typeof DOMAIN_EVENT_TYPES)[number];
-export type DomainResourceType = "belief" | "evidence" | "question" | "edge" | "contradiction" | "worktree" | "topic" | "task" | "ontology" | "context" | "identity" | "webhook";
-export type DomainActorType = "human" | "agent" | "service";
-export type DomainEventData = Record<string, unknown>;
-export type DomainEvent = {
-    eventId: string;
-    type: DomainEventType | string;
-    version: typeof DOMAIN_EVENT_VERSION;
-    timestamp: number;
-    tenantId?: string;
-    workspaceId?: string;
-    topicId: string;
-    resourceId: string;
-    resourceType: DomainResourceType | string;
-    actorId: string;
-    actorType: DomainActorType;
-    data: DomainEventData;
-    correlationId?: string;
-    expiresAt: number;
-};
-export type CreateDomainEventInput = {
-    eventId?: string;
-    timestamp?: number;
-    tenantId?: string;
-    workspaceId?: string;
-    topicId: string;
-    type: DomainEventType | string;
-    resourceId: string;
-    resourceType: DomainResourceType | string;
-    actorId: string;
-    actorType: DomainActorType;
-    data?: DomainEventData;
-    correlationId?: string;
-    retentionDays?: number;
-};
-export type EventCursor = {
-    timestamp: number;
-    eventId: string;
-};
-export type EventListQuery = {
-    topicId?: string;
-    after?: string;
-    types?: string[];
-    startTime?: number;
-    endTime?: number;
-    limit?: number;
-};
-export type EventListResult = {
-    events: DomainEvent[];
-    nextCursor: string | null;
-};
-export type WebhookSecretMode = "configured";
-export type WebhookRecord = {
-    id: string;
-    webhookId: string;
-    tenantId?: string;
-    workspaceId?: string;
-    topicId?: string;
-    url: string;
-    events: string[];
-    active: boolean;
-    secretConfigured: boolean;
-    createdAt: number;
-    updatedAt: number;
-    createdBy: string;
-    updatedBy: string;
-    lastDeliveryAt?: number;
-    lastSuccessfulDeliveryAt?: number;
-};
-export type WebhookCreateInput = {
-    url: string;
-    events: string[];
-    secret: string;
-    topicId?: string;
-    active?: boolean;
-};
-export type WebhookUpdateInput = {
-    url?: string;
-    events?: string[];
-    secret?: string;
-    topicId?: string | null;
-    active?: boolean;
-};
-export type WebhookDeliveryStatus = "pending" | "delivering" | "succeeded" | "failed" | "dead_letter";
-export type WebhookDeliveryRecord = {
-    id: string;
-    deliveryId: string;
-    webhookId: string;
-    eventId: string;
-    eventType: string;
-    topicId: string;
-    status: WebhookDeliveryStatus;
-    attemptCount: number;
-    maxAttempts: number;
-    nextAttemptAt?: number;
-    lastAttemptAt?: number;
-    lastStatusCode?: number;
-    lastError?: string;
-    deliveredAt?: number;
-    createdAt: number;
-    updatedAt: number;
-};
-export type WebhookDeliveryAttemptRecord = {
-    id: string;
-    attemptId: string;
-    deliveryId: string;
-    webhookId: string;
-    eventId: string;
-    eventType: string;
-    attemptNumber: number;
-    status: "succeeded" | "failed";
-    statusCode?: number;
-    error?: string;
-    responseBody?: string;
-    durationMs?: number;
-    createdAt: number;
-};
-export type WebhookDeliveriesResult = {
-    deliveries: Array<WebhookDeliveryRecord & {
-        attempts?: WebhookDeliveryAttemptRecord[];
-    }>;
-};
-export type WebhookHealthResult = {
-    webhookId: string;
-    totalAttempts: number;
-    successfulAttempts: number;
-    failedAttempts: number;
-    successRate: number;
-    pendingDeliveries: number;
-    deadLetterDeliveries: number;
-    lastDeliveryAt?: number;
-    lastSuccessfulDeliveryAt?: number;
-};
-export type WebhookTestResult = {
-    webhookId: string;
-    deliveryId: string;
-    status: WebhookDeliveryStatus;
-    attempts: number;
-};
-export type ReplayEventsInput = EventListQuery & {
-    webhookId?: string;
-};
-export type ReplayEventsResult = EventListResult & {
-    replayedDeliveries?: number;
-    replayedWebhookId?: string;
-};
-export declare function eventPatternToRegExp(pattern: string): RegExp;
-export declare function matchesEventPattern(eventType: string, pattern: string): boolean;
-export declare function matchesAnyEventPattern(eventType: string, patterns: readonly string[]): boolean;
-export declare function createEventId(): string;
-export declare function normalizeRetentionDays(value: number | undefined): number;
-export declare function buildDomainEvent(input: CreateDomainEventInput): DomainEvent;
-export declare function compareEventCursor(left: EventCursor, right: EventCursor): number;
-export declare function encodeEventCursor(cursor: EventCursor): string;
-export declare function decodeEventCursor(cursor: string | undefined): EventCursor | null;
-export declare function isAfterCursor(event: Pick<DomainEvent, "timestamp" | "eventId">, cursor: EventCursor | null): boolean;
-export declare function sortEventsByCursor<T extends Pick<DomainEvent, "timestamp" | "eventId">>(events: readonly T[]): T[];
-export declare function inferActorType(args: {
-    sessionType?: "agent" | "user";
-    authMode?: string;
-    principalType?: string;
-}): DomainActorType;
-export declare function emitDomainEvent(invokeMutation: (reference: any, args: CreateDomainEventInput) => Promise<unknown>, input: CreateDomainEventInput): Promise<unknown>;
-export declare function assertValidWebhookUrl(url: string): string;
-export declare function normalizeWebhookPatterns(patterns: readonly string[]): string[];
-export declare function assertValidWebhookSecret(secret: string): string;
-export declare function computeWebhookSignature(payload: string, secret: string): Promise<string>;
-export declare function nextDeliveryAttemptAt(currentAttemptCount: number, now?: number): number | undefined;
-export declare function resolveDeliveryFailureStatus(attemptCount: number): WebhookDeliveryStatus;
-export declare function sanitizeWebhookRecord(value: Record<string, unknown>): WebhookRecord;
-export declare function truncateWebhookResponseBody(responseBody: string | undefined, maxLength?: number): string | undefined;