@axiom-lattice/protocols 4.5.0 → 4.6.1

package/src/RunScope.ts

@@ -0,0 +1,44 @@
+/**
+ * Canonical run-scope extraction.
+ *
+ * An execution runConfig carries the same scope twice: the parsed fields
+ * (`projectId`, `workspaceId`) and the header-shaped fields (`x-project-id`,
+ * `x-workspace-id`). Internal propagation has historically overwritten one
+ * without the other, so a reader that picks a single field can silently lose a
+ * real scope (and later fall back to the `"default"` sentinel). Readers must
+ * resolve scope through one shared rule instead.
+ */
+
+/** Returns the first non-empty string among the candidates, else `undefined`. */
+export function firstNonEmptyString(...values: unknown[]): string | undefined {
+  for (const value of values) {
+    if (typeof value === "string" && value.length > 0) return value;
+  }
+  return undefined;
+}
+
+/** Workspace/project execution scope; each field absent when not supplied. */
+export interface RunScope {
+  workspaceId?: string;
+  projectId?: string;
+}
+
+/**
+ * Reads the authoritative execution scope from a runConfig bag.
+ *
+ * Prefers the parsed field and falls back to the header-shaped field for each
+ * of project and workspace. Missing or empty values resolve to `undefined`
+ * (never the `"default"` sentinel).
+ *
+ * @param runConfig - Untrusted execution runConfig bag.
+ * @returns Workspace/project scope, each absent when no non-empty value exists.
+ */
+export function resolveRunScope(runConfig: unknown): RunScope {
+  const rc = runConfig && typeof runConfig === "object" && !Array.isArray(runConfig)
+    ? runConfig as Record<string, unknown>
+    : {};
+  return {
+    workspaceId: firstNonEmptyString(rc.workspaceId, rc["x-workspace-id"]),
+    projectId: firstNonEmptyString(rc.projectId, rc["x-project-id"]),
+  };
+}

package/src/__tests__/RunScope.test.ts

@@ -0,0 +1,38 @@
+import { firstNonEmptyString, resolveRunScope } from "../RunScope";
+
+describe("firstNonEmptyString", () => {
+  it("returns the first non-empty string", () => {
+    expect(firstNonEmptyString(undefined, "", null, 0, "a", "b")).toBe("a");
+  });
+
+  it("returns undefined when no candidate is a non-empty string", () => {
+    expect(firstNonEmptyString(undefined, "", null, 42, {})).toBeUndefined();
+  });
+});
+
+describe("resolveRunScope", () => {
+  it("prefers the parsed fields", () => {
+    expect(resolveRunScope({
+      projectId: "p", workspaceId: "w", "x-project-id": "px", "x-workspace-id": "wx",
+    })).toEqual({ projectId: "p", workspaceId: "w" });
+  });
+
+  it("falls back to the header-shaped fields when the parsed fields are missing", () => {
+    expect(resolveRunScope({ "x-project-id": "px", "x-workspace-id": "wx" }))
+      .toEqual({ projectId: "px", workspaceId: "wx" });
+  });
+
+  it("treats empty parsed fields as absent and uses the header-shaped fallback", () => {
+    expect(resolveRunScope({ projectId: "", "x-project-id": "px" }))
+      .toEqual({ projectId: "px", workspaceId: undefined });
+  });
+
+  it("never invents the default sentinel for missing scope", () => {
+    expect(resolveRunScope({})).toEqual({ projectId: undefined, workspaceId: undefined });
+  });
+
+  it("tolerates non-record input", () => {
+    expect(resolveRunScope("nope")).toEqual({ projectId: undefined, workspaceId: undefined });
+    expect(resolveRunScope(null)).toEqual({ projectId: undefined, workspaceId: undefined });
+  });
+});

package/src/index.ts

@@ -29,6 +29,7 @@ export * from "./ConnectionStoreProtocol";
 export * from "./ChannelInstallationStoreProtocol";
 export * from "./MetricsServerConfigStoreProtocol";
 export * from "./McpServerConfigStoreProtocol";
+export * from "./ModelProviderProtocol";
 export * from "./UserStoreProtocol";
 export * from "./UserTenantLinkProtocol";
 export * from "./WorkflowTrackingStoreProtocol";
@@ -93,5 +94,6 @@ export * from "./SandboxPluginProtocol";
 // 导出通用类型
 export * from "./types";
 export * from "./TrustedRunContextProtocol";
+export * from "./RunScope";
 export * from "./OpenProtocol";
 export * from "./McpUiProtocol";