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

package/src/workflowClient.ts

@@ -0,0 +1,826 @@
+import {
+  createGatewayRequestClient,
+  type GatewayClientConfig,
+  LucernApiError,
+  randomIdempotencyKey,
+  toQueryString,
+} from "./coreClient";
+import {
+  asListItems,
+  createListResult,
+  mapAliasedList,
+  mapGatewayData,
+  normalizeTopicQuery,
+  resolveTopicId,
+  withTopicAlias,
+} from "./sdkSurface";
+import type {
+  LensPerspectiveType,
+  LensPromptTemplateReference,
+  LensStatus,
+  LensTaskTemplate,
+  LensWorkflowTemplate,
+} from "./contracts/lensWorkflow";
+import type {
+  WorkflowAutoFixPolicy,
+  WorkflowProofArtifact,
+  WorkflowStaffingHint,
+} from "./contracts/workflowRuntime";
+import type {
+  AddWorktreeResponse,
+  CompleteTaskResponse,
+  CreateBranchResponse,
+  CreateLensResponse,
+  CreateTaskResponse,
+  JsonObject,
+  JsonValue,
+  LensTopicBindingResponse,
+  ListBranchesResponse,
+  ListLensesResponse,
+  ListTopicsResponse,
+  ListWorktreesResponse,
+  MergeWorktreeResponse,
+  OpenPullRequestResponse,
+  PushWorktreeResponse,
+  SwitchTopicContextResponse,
+  TopicIdentifierInput,
+  UpdateTaskResponse,
+  WorkflowBranchRecord,
+  WorkflowLensRecord,
+  WorkflowTopicRecord,
+  WorkflowWorktreeRecord,
+} from "./types";
+
+export { LucernApiError };
+export type { PlatformGatewaySuccess } from "./coreClient";
+export type {
+  AddWorktreeResponse,
+  CompleteTaskResponse,
+  CreateBranchResponse,
+  CreateLensResponse,
+  CreateTaskResponse,
+  LensTopicBindingResponse,
+  ListBranchesResponse,
+  ListLensesResponse,
+  ListTopicsResponse,
+  ListWorktreesResponse,
+  MergeWorktreeResponse,
+  OpenPullRequestResponse,
+  PushWorktreeResponse,
+  SwitchTopicContextResponse,
+  UpdateTaskResponse,
+} from "./types";
+
+/** Configuration for the workflow client. */
+export type WorkflowClientConfig = GatewayClientConfig;
+
+/** Lifecycle status of a workflow branch. */
+export type WorkflowBranchStatus = "dormant" | "active" | "archived";
+
+/** Lifecycle status of a workflow lens. */
+export type WorkflowLensStatus = LensStatus;
+
+/** Analytical perspective type for a lens overlay. */
+export type WorkflowLensPerspectiveType = LensPerspectiveType;
+
+/** Lifecycle status of a workflow worktree. */
+export type WorkflowWorktreeStatus =
+  | "planning"
+  | "active"
+  | "paused"
+  | "completed"
+  | "merged"
+  | "failed"
+  | "archived";
+
+/** Possible outcomes when merging worktree findings into the main belief line. */
+export type WorkflowMergeOutcome =
+  | "validated"
+  | "invalidated"
+  | "forked"
+  | "inconclusive";
+
+/** Input for creating a new workflow worktree. */
+export type AddWorktreeInput = {
+  title: string;
+  topicId?: string;
+  branchId?: string;
+  objective?: string;
+  hypothesis?: string;
+  beliefIds?: string[];
+  autoShape?: boolean;
+  domainPackId?: string;
+  executionOrder?: number;
+  dependsOn?: string[];
+  blocks?: string[];
+  gate?: string;
+  proofArtifacts?: WorkflowProofArtifact[];
+  staffingHint?: WorkflowStaffingHint | string;
+  lastReconciledAt?: number;
+  autoFixPolicy?: WorkflowAutoFixPolicy;
+} & TopicIdentifierInput;
+
+/** Input for merging worktree findings with belief confidence outcomes. */
+export type MergeInput = {
+  outcomes: Array<{
+    beliefId: string;
+    confidence: number;
+    rationale: string;
+  }>;
+  summary?: string;
+};
+
+/** Input for updating the beliefs and questions tracked by a worktree. */
+export type UpdateWorktreeTargetsInput = {
+  worktreeId: string;
+  addBeliefIds?: string[];
+  addQuestionIds?: string[];
+  removeBeliefIds?: string[];
+  removeQuestionIds?: string[];
+};
+
+/** Input for marking a worktree complete with recorded outcomes. */
+export type CompleteWorktreeInput = {
+  worktreeId: string;
+  keyFindings?: string[];
+  decisionsReached?: string[];
+  nextSteps?: string[];
+};
+
+/** Input for moving a worktree forward to its next phase. */
+export type AdvanceWorktreePhaseInput = {
+  worktreeId: string;
+};
+
+/** Input for forcing a worktree into a specific phase. */
+export type SetWorktreePhaseInput = {
+  worktreeId: string;
+  phase: string;
+};
+
+/** Input for patching arbitrary structured worktree state. */
+export type PatchWorktreeStateInput = {
+  worktreeId: string;
+  patch: JsonObject;
+};
+
+/** Input for batch-creating worktrees through the workflow surface. */
+export type BulkCreateWorktreesInput = {
+  worktrees: unknown[];
+};
+
+/** Input for listing accessible topic contexts. */
+export type ListTopicsInput = {
+  includeShared?: boolean;
+  limit?: number;
+};
+
+/** Input for switching the active topic context by name. */
+export type SwitchTopicContextInput = {
+  targetTopicName: string;
+};
+
+/** Input for creating a workflow task linked to a question or worktree. */
+export type CreateTaskInput = {
+  title: string;
+  topicId?: string;
+  taskType?: "research" | "interview" | "analysis" | "data_collection";
+  linkedQuestionId?: string;
+  linkedWorktreeId?: string;
+  linkedBeliefId?: string;
+  description?: string;
+  priority?: "low" | "medium" | "high" | "urgent";
+} & TopicIdentifierInput;
+
+/** Input for marking a workflow task as completed with an output summary. */
+export type CompleteTaskInput = {
+  outputSummary: string;
+  evidenceCreated?: boolean;
+};
+
+/** Input for partially updating an existing workflow task. */
+export type UpdateTaskInput = {
+  title?: string;
+  description?: string;
+  linkedBeliefId?: string;
+  linkedQuestionId?: string;
+  linkedWorktreeId?: string;
+  priority?: "critical" | "high" | "medium" | "low";
+  status?: "todo" | "in_progress" | "blocked" | "done";
+};
+
+function normalizeLensQuery<T extends { topicId?: string }>(
+  value: T
+) {
+  const topicId = resolveTopicId(value);
+  return {
+    ...value,
+    ...(topicId ? { topicId } : {}),
+  };
+}
+
+/**
+ * Create the workflow client for lenses, legacy branches, worktrees, context,
+ * and tasks.
+ * @param config - Gateway transport configuration.
+ * @returns An object with methods to manage branches, lenses, worktrees, topics, and tasks.
+ */
+export function createWorkflowClient(config: WorkflowClientConfig = {}) {
+  const gateway = createGatewayRequestClient(config);
+  const client = {
+    /**
+     * List workflow branches for a topic scope.
+     */
+    async listBranches(query: {
+      topicId?: string;
+      status?: WorkflowBranchStatus;
+      limit?: number;
+    } & TopicIdentifierInput) {
+      return gateway.request<ListBranchesResponse>({
+        path: `/api/platform/v1/workflow/branches${toQueryString(
+          normalizeTopicQuery(query)
+        )}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          mapAliasedList<WorkflowBranchRecord, "branches">(data, "branches")
+        )
+      );
+    },
+
+    /**
+     * Create a workflow branch.
+     */
+    async createBranch(
+      input: {
+        name: string;
+        topicId?: string;
+        description?: string;
+        metadata?: JsonObject;
+      } & TopicIdentifierInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<CreateBranchResponse>({
+        path: "/api/platform/v1/workflow/branches",
+        method: "POST",
+        body: normalizeTopicQuery(input),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withTopicAlias(data as Record<string, unknown>) as CreateBranchResponse
+        )
+      );
+    },
+
+    /**
+     * List reusable lenses for a workspace or topic scope.
+     */
+    async listLenses(query: {
+      workspaceId?: string;
+      topicId?: string;
+      status?: WorkflowLensStatus;
+      perspectiveType?: WorkflowLensPerspectiveType;
+    } & TopicIdentifierInput) {
+      return gateway.request<ListLensesResponse>({
+        path: `/api/platform/v1/workflow/lenses${toQueryString(
+          normalizeLensQuery(query)
+        )}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          mapAliasedList<WorkflowLensRecord, "lenses">(data, "lenses")
+        )
+      );
+    },
+
+    /**
+     * Create a reusable workflow lens.
+     */
+    async createLens(
+      input: {
+        name: string;
+        workspaceId?: string;
+        topicId?: string;
+        description?: string;
+        perspectiveType: WorkflowLensPerspectiveType;
+        promptTemplates?: LensPromptTemplateReference[];
+        workflowTemplates?: LensWorkflowTemplate[];
+        taskTemplates?: LensTaskTemplate[];
+        filterCriteria?: JsonObject;
+      } & TopicIdentifierInput,
+      idempotencyKey?: string
+    ) {
+      const payload = normalizeLensQuery(input);
+      return gateway.request<CreateLensResponse>({
+        path: "/api/platform/v1/workflow/lenses",
+        method: "POST",
+        body: payload as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withTopicAlias(data as Record<string, unknown>) as CreateLensResponse
+        )
+      );
+    },
+
+    /**
+     * Apply an existing lens to a topic.
+     */
+    async applyLensToTopic(
+      input: {
+        lensId: string;
+        topicId?: string;
+        metadata?: JsonObject;
+      } & TopicIdentifierInput,
+      idempotencyKey?: string
+    ) {
+      const payload = normalizeLensQuery(input);
+      return gateway.request<LensTopicBindingResponse>({
+        path: "/api/platform/v1/workflow/lens-bindings",
+        method: "POST",
+        body: payload,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withTopicAlias(data as Record<string, unknown>) as LensTopicBindingResponse
+        )
+      );
+    },
+
+    /**
+     * Remove an applied lens from a topic.
+     */
+    async removeLensFromTopic(
+      input: {
+        lensId: string;
+        topicId?: string;
+      } & TopicIdentifierInput,
+      idempotencyKey?: string
+    ) {
+      const topicId = resolveTopicId(input);
+      if (!topicId) {
+        throw new LucernApiError({
+          code: "INVALID_REQUEST",
+          message: "topicId is required",
+          status: 400,
+        });
+      }
+
+      return gateway.request<LensTopicBindingResponse>({
+        path: `/api/platform/v1/workflow/lens-bindings${toQueryString({
+          lensId: input.lensId,
+          topicId,
+        })}`,
+        method: "DELETE",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withTopicAlias(data as Record<string, unknown>) as LensTopicBindingResponse
+        )
+      );
+    },
+
+    /**
+     * List worktrees for a topic scope.
+     */
+    async listWorktrees(query: {
+      topicId?: string;
+      branchId?: string;
+      status?: WorkflowWorktreeStatus;
+      track?: string;
+      executionBand?: number;
+      limit?: number;
+    } & TopicIdentifierInput) {
+      const normalized = normalizeTopicQuery(query);
+      return gateway.request<ListWorktreesResponse>({
+        path: `/api/platform/v1/worktrees${toQueryString({
+          ...normalized,
+          track: query.track,
+          executionBand: query.executionBand,
+        })}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          mapAliasedList<WorkflowWorktreeRecord, "worktrees">(
+            data,
+            "worktrees"
+          )
+        )
+      );
+    },
+
+    /**
+     * List all worktrees across accessible topics.
+     */
+    async listAllWorktrees(query: {
+      status?: WorkflowWorktreeStatus;
+      track?: string;
+      executionBand?: number;
+      limit?: number;
+    } = {}) {
+      return gateway.request<ListWorktreesResponse>({
+        path: `/api/platform/v1/worktrees${toQueryString({
+          status: query.status,
+          track: query.track,
+          executionBand: query.executionBand,
+          limit: query.limit,
+        })}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) => {
+          const record =
+            data && typeof data === "object" && !Array.isArray(data)
+              ? (data as Record<string, unknown>)
+              : {};
+          const list = mapAliasedList<WorkflowWorktreeRecord, "worktrees">(
+            data,
+            "worktrees"
+          );
+          return {
+            ...list,
+            ...(record.tracks &&
+            typeof record.tracks === "object" &&
+            !Array.isArray(record.tracks)
+              ? { tracks: record.tracks as Record<string, number> }
+              : {}),
+            ...(record.bands &&
+            typeof record.bands === "object" &&
+            !Array.isArray(record.bands)
+              ? { bands: record.bands as Record<string, number> }
+              : {}),
+          } as ListWorktreesResponse;
+        })
+      );
+    },
+
+    /**
+     * Create a workflow worktree.
+     */
+    async createWorktree(input: AddWorktreeInput, idempotencyKey?: string) {
+      return gateway.request<AddWorktreeResponse>({
+        path: "/api/platform/v1/worktrees",
+        method: "POST",
+        body: normalizeTopicQuery(input),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withTopicAlias(data as Record<string, unknown>) as AddWorktreeResponse
+        )
+      );
+    },
+
+    /**
+     * @deprecated Use createWorktree.
+     */
+    async addWorktree(input: AddWorktreeInput, idempotencyKey?: string) {
+      return client.createWorktree(input, idempotencyKey);
+    },
+
+    /**
+     * Merge a worktree into the main belief line.
+     */
+    async merge(
+      worktreeId: string,
+      input: MergeInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<MergeWorktreeResponse>({
+        path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/merge`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Activate a planning worktree.
+     */
+    async activateWorktree(worktreeId: string, idempotencyKey?: string) {
+      return gateway.request<AddWorktreeResponse>({
+        path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/activate`,
+        method: "POST",
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withTopicAlias(data as Record<string, unknown>) as AddWorktreeResponse
+        )
+      );
+    },
+
+    /**
+     * Update targeted beliefs/questions for a worktree.
+     */
+    async updateWorktreeTargets(
+      input: UpdateWorktreeTargetsInput,
+      idempotencyKey?: string
+    ) {
+      const { worktreeId, ...body } = input;
+      return gateway.request<AddWorktreeResponse>({
+        path: `/api/platform/v1/worktrees/${encodeURIComponent(worktreeId)}/targets`,
+        method: "POST",
+        body,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withTopicAlias(data as Record<string, unknown>) as AddWorktreeResponse
+        )
+      );
+    },
+
+    /**
+     * Mark a worktree record complete.
+     */
+    async completeWorktree(
+      input: CompleteWorktreeInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/worktrees/complete",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Advance a worktree to its next lifecycle phase.
+     */
+    async advanceWorktreePhase(
+      input: AdvanceWorktreePhaseInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/worktrees/advance-phase",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Force a worktree into a specific lifecycle phase.
+     */
+    async setWorktreePhase(
+      input: SetWorktreePhaseInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/worktrees/set-phase",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Patch opaque worktree state for orchestration flows.
+     */
+    async patchWorktreeState(
+      input: PatchWorktreeStateInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/worktrees/patch-state",
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Batch create worktree records.
+     */
+    async bulkCreateWorktrees(
+      input: BulkCreateWorktreesInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<Record<string, unknown>>({
+        path: "/api/platform/v1/worktrees/bulk",
+        method: "POST",
+        body: input as unknown as JsonObject,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Open a pull request for a worktree.
+     */
+    async openPullRequest(
+      worktreeId: string,
+      input: {
+        summary: string;
+        reviewers?: string[];
+        status?:
+          | "pending_review"
+          | "changes_requested"
+          | "approved"
+          | "blocked";
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<OpenPullRequestResponse>({
+        path: `/api/platform/v1/workflow/worktrees/${encodeURIComponent(worktreeId)}/pull-request`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Push scored worktree findings into another context.
+     */
+    async push(
+      worktreeId: string,
+      input: {
+        targetContext: string;
+        beliefIds?: string[];
+        metadata?: JsonObject;
+      },
+      idempotencyKey?: string
+    ) {
+      return gateway.request<PushWorktreeResponse>({
+        path: `/api/platform/v1/workflow/worktrees/${encodeURIComponent(worktreeId)}/push`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * List accessible topic contexts.
+     */
+    async listTopics(query: ListTopicsInput = {}) {
+      return gateway.request<ListTopicsResponse>({
+        path: `/api/platform/v1/workflow/topics${toQueryString({
+          includeShared:
+            typeof query.includeShared === "boolean"
+              ? query.includeShared
+                ? "true"
+                : "false"
+              : undefined,
+          limit: query.limit,
+        })}`,
+      }).then((response) =>
+        mapGatewayData(response, (data) => {
+          const items = asListItems<WorkflowTopicRecord>(data, "topics").map(
+            (item) =>
+              withTopicAlias(
+                item as Record<string, unknown>
+              ) as WorkflowTopicRecord
+          );
+          const record =
+            data && typeof data === "object"
+              ? (data as Record<string, unknown>)
+              : {};
+          return {
+            ...record,
+            ...createListResult(items, "topics"),
+            total:
+              typeof record.total === "number" ? record.total : items.length,
+          } as ListTopicsResponse;
+        })
+      );
+    },
+
+    /**
+     * Switch the active context by topic or project name.
+     */
+    async switchTopicContext(
+      input: SwitchTopicContextInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<SwitchTopicContextResponse>({
+        path: "/api/platform/v1/workflow/topics/switch",
+        method: "POST",
+        body: {
+          targetTopicName: input.targetTopicName,
+        },
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      }).then((response) =>
+        mapGatewayData(response, (data) =>
+          withTopicAlias(
+            data as Record<string, unknown>
+          ) as SwitchTopicContextResponse
+        )
+      );
+    },
+
+    /**
+     * Create a workflow task.
+     */
+    async createTask(input: CreateTaskInput, idempotencyKey?: string) {
+      return gateway.request<CreateTaskResponse>({
+        path: "/api/platform/v1/workflow/tasks",
+        method: "POST",
+        body: normalizeTopicQuery(input),
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Complete a workflow task.
+     */
+    async completeTask(
+      taskId: string,
+      input: CompleteTaskInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<CompleteTaskResponse>({
+        path: `/api/platform/v1/workflow/tasks/${encodeURIComponent(taskId)}/complete`,
+        method: "POST",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * Update a workflow task.
+     */
+    async updateTask(
+      taskId: string,
+      input: UpdateTaskInput,
+      idempotencyKey?: string
+    ) {
+      return gateway.request<UpdateTaskResponse>({
+        path: `/api/platform/v1/workflow/tasks/${encodeURIComponent(taskId)}`,
+        method: "PATCH",
+        body: input,
+        idempotencyKey: idempotencyKey ?? randomIdempotencyKey(),
+      });
+    },
+
+    /**
+     * @deprecated Use createBranch.
+     */
+    async createPillar(
+      input: {
+        name: string;
+        topicId?: string;
+        description?: string;
+        metadata?: JsonObject;
+      } & TopicIdentifierInput,
+      idempotencyKey?: string
+    ) {
+      return client.createBranch(input, idempotencyKey);
+    },
+
+    /**
+     * @deprecated Use addWorktree.
+     */
+    async createSprint(
+      input: {
+        title: string;
+        topicId?: string;
+        branchId?: string;
+        hypothesis?: string;
+        beliefIds?: string[];
+      } & TopicIdentifierInput,
+      idempotencyKey?: string
+    ) {
+      return client.createWorktree(input, idempotencyKey);
+    },
+
+    /**
+     * @deprecated Use merge.
+     */
+    async completeSprint(
+      worktreeId: string,
+      input: MergeInput,
+      idempotencyKey?: string
+    ) {
+      return client.merge(worktreeId, input, idempotencyKey);
+    },
+
+    /**
+     * @deprecated Use openPullRequest.
+     */
+    async requestReview(
+      worktreeId: string,
+      input: {
+        summary: string;
+        reviewers?: string[];
+        status?:
+          | "pending_review"
+          | "changes_requested"
+          | "approved"
+          | "blocked";
+      },
+      idempotencyKey?: string
+    ) {
+      return client.openPullRequest(worktreeId, input, idempotencyKey);
+    },
+
+    /**
+     * @deprecated Use push.
+     */
+    async publishFindings(
+      worktreeId: string,
+      input: {
+        targetContext: string;
+        beliefIds?: string[];
+        metadata?: JsonObject;
+      },
+      idempotencyKey?: string
+    ) {
+      return client.push(worktreeId, input, idempotencyKey);
+    },
+  };
+
+  return client;
+}