@stigmer/server 3.38.0 → 3.38.2

package/src/domain/platform/__tests__/platform.test.ts

@@ -14,7 +14,9 @@
  *     executioncontext decrypt lane uses, bound to exactly the named
  *     execution id;
  *   - getRunnerBootstrapConfig echoes the configured Temporal coordinates
- *     with the token fields empty (minting a proxy token is cloud-only);
+ *     with the token fields empty (minting a proxy token is cloud-only),
+ *     and publishes the runner-bootstrap address rather than the one the
+ *     server dials when the two differ (stigmer#1357);
  *   - getServerInfo reports the build stamp by default and the release a
  *     library consumer states through ComposeOptions.version otherwise
  *     (stigmer#1168: unbundled, the stamp is always "dev"), and a
@@ -278,11 +280,61 @@ describe("platform domain (composed with a stated version)", () => {
   });
 });
 
+/**
+ * stigmer#1357 through the real stack: a server that dials Temporal by a
+ * name its runners cannot resolve publishes the address they can, from
+ * the environment through loadConfig and the composition root to the
+ * wire. The composed-server arm above is the default: with no override,
+ * the published address is the server's own.
+ */
+describe("platform domain (composed for runners off the server's network)", () => {
+  let server: ComposedServer;
+  let client: PlatformClient;
+  let dir: string;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(
+      path.join(tmpdir(), "platform-domain-runner-address-test-"),
+    );
+    vi.stubEnv("STIGMER_ENCRYPTION_KEY", ENC_KEY.toString("base64"));
+    server = await composeServer({
+      config: loadConfig({
+        STIGMER_MODEL_REGISTRY_REFRESH: "off",
+        DB_PATH: path.join(dir, "stigmer.db"),
+        ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+        TEMPORAL_HOST_PORT: "127.0.0.1:7777",
+        TEMPORAL_NAMESPACE: "conformance-ns",
+        STIGMER_RUNNER_BOOTSTRAP_TEMPORAL_ADDRESS: "temporal.example.test:7233",
+      }),
+      logger: silentLogger,
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+    const port = await server.start();
+    client = createClient(
+      PlatformQueryController,
+      createGrpcTransport({ baseUrl: `http://127.0.0.1:${port}` }),
+    );
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+    vi.unstubAllEnvs();
+  });
+
+  it("getRunnerBootstrapConfig publishes the runner-bootstrap address, with the server's namespace", async () => {
+    const config = await client.getRunnerBootstrapConfig({});
+    expect(config.temporalAddress).toBe("temporal.example.test:7233");
+    expect(config.temporalNamespace).toBe("conformance-ns");
+  });
+});
+
 describe("platform domain (keyless runner-token service)", () => {
   it("a keyless service answers not-minted — fail-soft, never an error", async () => {
     const transport = createRouterTransport((router) => {
       registerPlatformServices(router, {
-        temporalHostPort: "localhost:7233",
+        runnerBootstrapTemporalAddress: "localhost:7233",
         temporalNamespace: "default",
         runnerAuthService: newExecutionScopedRunnerCredentialProvider(
           RunnerAuthService.create(undefined),
@@ -318,7 +370,7 @@ describe("platform domain (license status)", () => {
   function clientWith(provider: LicenseStatusProvider) {
     const transport = createRouterTransport((router) => {
       registerPlatformServices(router, {
-        temporalHostPort: "localhost:7233",
+        runnerBootstrapTemporalAddress: "localhost:7233",
         temporalNamespace: "default",
         runnerAuthService: newExecutionScopedRunnerCredentialProvider(
           RunnerAuthService.create(undefined),

package/src/domain/platform/controller.ts

@@ -78,12 +78,14 @@ import { TOKEN_TYPE_EXECUTION_SCOPED } from "../../runnerauth/runnerauth.js";
 
 export interface PlatformControllerDeps {
   /**
-   * Temporal coordinates this server runs against, published to embedded
-   * runners. In OSS the server and its runners are co-located, so the
-   * address the server itself dials is the one runners should dial too —
-   * no internal/external split (unlike Stigmer Cloud).
+   * The Temporal coordinates published to embedded runners. The address
+   * is the one a runner should dial, which is not always the one this
+   * server dials: a clustered server reaches Temporal by an internal name
+   * its desktop runners cannot resolve (stigmer#1357). The composition
+   * root passes config.runnerBootstrapTemporalAddress, which defaults to
+   * the server's own address; the namespace is the server's.
    */
-  readonly temporalHostPort: string;
+  readonly runnerBootstrapTemporalAddress: string;
   readonly temporalNamespace: string;
   /**
    * Mints the execution-scoped tokens getRunnerScopedToken hands to
@@ -202,7 +204,9 @@ async function getLicenseStatus(
 
 /**
  * Go GetRunnerBootstrapConfig: the Temporal coordinates an embedded runner
- * should connect to so it can self-bootstrap from a token alone. The
+ * should connect to so it can self-bootstrap from a token alone: the
+ * address deps name for runners, never assumed to be the server's own
+ * (the proto's "the one reachable by the caller"). The
  * RunnerAccessToken / TokenType / RunnerAccessTokenExpiresInSeconds fields
  * are intentionally left empty in OSS: minting an iss=stigmer proxy token
  * is a cloud-only capability (OSS has no Cursor BiDi proxy to authenticate
@@ -221,7 +225,7 @@ async function getRunnerBootstrapConfig(
   ctx: HandlerContext,
 ): Promise<GetRunnerBootstrapConfigOutput> {
   const output = create(GetRunnerBootstrapConfigOutputSchema, {
-    temporalAddress: deps.temporalHostPort,
+    temporalAddress: deps.runnerBootstrapTemporalAddress,
     temporalNamespace: deps.temporalNamespace,
   });
   const bootstrapCredentials =

package/src/domain/workflowexecution/__tests__/store-faults.test.ts

@@ -45,7 +45,12 @@ import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/
 
 import { createLogger } from "../../../boot/logger.js";
 import { callerIdentityKey } from "../../../pipeline/interceptors/auth.js";
-import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import {
+  errorOf,
+  failingStore,
+  testCallerIdentity,
+  untouchable,
+} from "../../../pipeline/__tests__/support.js";
 import { RequestContext } from "../../../pipeline/request-context.js";
 import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
 import { ResourceNotFoundError } from "../../../store/interface.js";
@@ -80,35 +85,10 @@ const WORKFLOW_ID = "wfl_storefault";
 const EXECUTION_FAULT_COPY = "failed to load workflow execution";
 const WORKFLOW_FAULT_COPY = "failed to load workflow";
 
-/** A dependency the call must never reach once its load has failed. */
-function untouchable<T extends object>(name: string): T {
-  return new Proxy({} as T, {
-    get(_target, prop) {
-      throw new Error(`${name}.${String(prop)} reached after a failed load`);
-    },
-  });
-}
-
-/** A store whose every read fails with the given error. */
-function failingStore(error: Error): Store {
-  return {
-    getResource: () => Promise.reject(error),
-  } as unknown as Store;
-}
-
 const MISSING = (): Error =>
   new ResourceNotFoundError(`workflow_execution/${EXECUTION_ID}`);
 const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
 
-async function errorOf(call: () => Promise<unknown>): Promise<ConnectError> {
-  const error = await call().then(
-    () => undefined,
-    (e: unknown) => e,
-  );
-  expect(error, "the call must fail").toBeInstanceOf(ConnectError);
-  return error as ConnectError;
-}
-
 function handlerContext(): HandlerContext {
   const values = createContextValues();
   values.set(callerIdentityKey, testCallerIdentity());

package/src/index.ts

@@ -293,12 +293,14 @@ export { RequestContext } from "./pipeline/request-context.js";
 export {
   abortedError,
   alreadyExistsError,
+  ERROR_REASON_DOMAIN,
   failedPreconditionError,
   internalError,
   invalidArgumentError,
   notFoundError,
   unavailableError,
 } from "./pipeline/errors.js";
+export type { RefusalReason } from "./pipeline/errors.js";
 // The shared slug derivation (C2 Stage 3): extension-registered resource
 // kinds derive slugs with the SAME generator both editions pin
 // (ApiRequestResourceSlugGenerator parity) — the semantics live exactly

package/src/pipeline/__tests__/blind-not-found.test.ts

@@ -44,11 +44,6 @@ const PENDING: ReadonlyMap<string, number> = new Map([
   ["domain/artifact/controller.ts", 1],
   ["domain/environment/controller.ts", 1],
   ["domain/environment/steps.ts", 1],
-  ["domain/mcpserver/complete-oauth-connect.ts", 1],
-  ["domain/mcpserver/connect.ts", 1],
-  ["domain/mcpserver/controller.ts", 1],
-  ["domain/mcpserver/initiate-oauth-connect.ts", 1],
-  ["domain/mcpserver/start-connect.ts", 2],
   ["domain/plugin/controller.ts", 1],
   ["domain/skill/controller.ts", 1],
   ["domain/workflow/controller.ts", 1],

package/src/pipeline/__tests__/errors.test.ts

@@ -0,0 +1,72 @@
+/**
+ * The structured-refusal seam on failedPreconditionError: a reason rides
+ * as a google.rpc.ErrorInfo detail beside the byte-pinned message, and
+ * reaches a client over a real Connect call. The SDK's getErrorReason
+ * reads the detail the same way the round trip below does, so a refusal
+ * this helper builds is one a console can branch on.
+ */
+import { create } from "@bufbuild/protobuf";
+import {
+  Code,
+  ConnectError,
+  createClient,
+  createRouterTransport,
+} from "@connectrpc/connect";
+import { ErrorInfoSchema } from "@stigmer/protos/google/rpc/error_details_pb";
+import { Health, HealthCheckRequestSchema } from "@stigmer/protos/grpc/health/v1/health_pb";
+import { describe, expect, it } from "vitest";
+
+import { ERROR_REASON_DOMAIN, failedPreconditionError } from "../errors.js";
+
+describe("failedPreconditionError", () => {
+  it("carries no detail without a reason", () => {
+    const error = failedPreconditionError("Add a payment method first.");
+
+    expect(error.code).toBe(Code.FailedPrecondition);
+    expect(error.rawMessage).toBe("Add a payment method first.");
+    expect(error.findDetails(ErrorInfoSchema)).toEqual([]);
+  });
+
+  it("attaches the reason as an ErrorInfo detail and leaves the message as written", () => {
+    const error = failedPreconditionError("Teams need the Team plan or above.", {
+      reason: "PLAN_UPGRADE_REQUIRED",
+      metadata: { feature: "teams", org_id: "org_1" },
+    });
+
+    expect(error.rawMessage).toBe("Teams need the Team plan or above.");
+    const [info] = error.findDetails(ErrorInfoSchema);
+    expect(info?.reason).toBe("PLAN_UPGRADE_REQUIRED");
+    expect(info?.domain).toBe(ERROR_REASON_DOMAIN);
+    expect(info?.metadata).toEqual({ feature: "teams", org_id: "org_1" });
+  });
+
+  it("delivers the detail to a client across a Connect call", async () => {
+    const transport = createRouterTransport((router) => {
+      router.service(Health, {
+        check: () => {
+          throw failedPreconditionError("A saved payment method is required.", {
+            reason: "PAYMENT_METHOD_REQUIRED",
+            metadata: { org_id: "org_2" },
+          });
+        },
+        list: () => ({ statuses: {} }),
+        watch: async function* () {},
+      });
+    });
+    const client = createClient(Health, transport);
+
+    const caught = await client.check(create(HealthCheckRequestSchema)).then(
+      () => undefined,
+      (error: unknown) => error,
+    );
+
+    expect(caught).toBeInstanceOf(ConnectError);
+    const error = caught as ConnectError;
+    expect(error.code).toBe(Code.FailedPrecondition);
+    expect(error.rawMessage).toBe("A saved payment method is required.");
+    const [info] = error.findDetails(ErrorInfoSchema);
+    expect(info?.reason).toBe("PAYMENT_METHOD_REQUIRED");
+    expect(info?.domain).toBe(ERROR_REASON_DOMAIN);
+    expect(info?.metadata).toEqual({ org_id: "org_2" });
+  });
+});

package/src/pipeline/__tests__/support.ts

@@ -1,16 +1,31 @@
 /**
- * Shared test identity for RequestContext construction (O2, ruling Q3):
- * the identity parameter is required, so every test constructs one
- * explicitly — never a hidden default that could mask a missed threading
- * site in production code. Overrides let adversarial tests pin specific
- * caller classes.
+ * Shared test fixtures for the pipeline and the domains.
+ *
+ * The caller identity for RequestContext construction: the identity
+ * parameter is required, so every test constructs one explicitly — never a
+ * hidden default that could mask a missed threading site in production
+ * code. Overrides let adversarial tests pin specific caller classes.
+ *
+ * The run-gate authorizer, which isolates the AuthorizeRunTarget splice from
+ * every other authorization site on a chain.
+ *
+ * The store-fault helpers the per-domain `store-faults` tests share: a store
+ * whose reads fail with a chosen error, a dependency that must never be
+ * reached once a load has failed, and the ConnectError a failing call
+ * rejects with. Together they pin the error contract's store-fault rule
+ * (`src/pipeline/errors.ts`): a typed not-found answers NotFound, any other
+ * store failure a sanitized Internal.
  */
+import { ConnectError } from "@connectrpc/connect";
+import { expect } from "vitest";
+
 import type {
   Authorizer,
   AuthzCheck,
   AuthzDecision,
 } from "../../extensions/authorizer.js";
 import type { CallerIdentity } from "../../extensions/identity.js";
+import type { Store } from "../../store/interface.js";
 import { isRunGateCheck } from "../steps/authorize-run-target.js";
 
 export function testCallerIdentity(
@@ -52,3 +67,31 @@ export function runGateOnlyAuthorizer(decide: () => AuthzDecision): {
     },
   };
 }
+
+/** A dependency the call must never reach once its load has failed. */
+export function untouchable<T extends object>(name: string): T {
+  return new Proxy({} as T, {
+    get(_target, prop) {
+      throw new Error(`${name}.${String(prop)} reached after a failed load`);
+    },
+  });
+}
+
+/** A store whose every read fails with the given error. */
+export function failingStore(error: Error): Store {
+  return {
+    getResource: () => Promise.reject(error),
+  } as unknown as Store;
+}
+
+/** The ConnectError `call` rejects with; fails the test if it resolves. */
+export async function errorOf(
+  call: () => Promise<unknown>,
+): Promise<ConnectError> {
+  const error = await call().then(
+    () => undefined,
+    (e: unknown) => e,
+  );
+  expect(error, "the call must fail").toBeInstanceOf(ConnectError);
+  return error as ConnectError;
+}

package/src/pipeline/errors.ts

@@ -9,8 +9,31 @@
  * text can carry storage-engine detail or filesystem paths, and on an
  * anonymous surface that is information disclosure. The cause rides
  * ConnectError.cause for server-side logs; it never crosses the wire.
+ *
+ * A refusal a client should branch on, rather than parse its copy, also
+ * carries a google.rpc.ErrorInfo detail (domain "stigmer.ai"), the
+ * platform's structured-refusal contract that the SDK's getErrorReason
+ * reads. Its reasons are documented on the refusing RPC's proto comment.
+ * The detail rides beside the message and never changes it, so the copy
+ * stays byte-pinned. A detail survives the pipeline and the transport
+ * boundary; only the visitor sanitizer, which rewrites an anonymous
+ * caller's error, drops it (interceptors/error-boundary.ts).
  */
+import { create } from "@bufbuild/protobuf";
 import { Code, ConnectError } from "@connectrpc/connect";
+import { ErrorInfoSchema } from "@stigmer/protos/google/rpc/error_details_pb";
+
+/** The domain every structured refusal reason is issued under. */
+export const ERROR_REASON_DOMAIN = "stigmer.ai";
+
+/**
+ * A machine-readable refusal reason: an UPPER_SNAKE code and the facts a
+ * client needs to act on it, both documented on the refusing RPC.
+ */
+export interface RefusalReason {
+  readonly reason: string;
+  readonly metadata?: Readonly<Record<string, string>>;
+}
 
 /** Go NotFoundError: "%s not found: %s". */
 export function notFoundError(resource: string, id: string): ConnectError {
@@ -32,10 +55,26 @@ export function alreadyExistsError(resource: string, id: string): ConnectError {
 
 /**
  * Go FailedPreconditionError — the system is not in a state required for
- * the operation (vs AlreadyExists, which tells the caller to stop).
+ * the operation (vs AlreadyExists, which tells the caller to stop). With a
+ * reason, the refusal also carries it as an ErrorInfo detail.
  */
-export function failedPreconditionError(message: string): ConnectError {
-  return new ConnectError(message, Code.FailedPrecondition);
+export function failedPreconditionError(
+  message: string,
+  reason?: RefusalReason,
+): ConnectError {
+  if (reason === undefined) {
+    return new ConnectError(message, Code.FailedPrecondition);
+  }
+  return new ConnectError(message, Code.FailedPrecondition, undefined, [
+    {
+      desc: ErrorInfoSchema,
+      value: create(ErrorInfoSchema, {
+        reason: reason.reason,
+        domain: ERROR_REASON_DOMAIN,
+        metadata: { ...reason.metadata },
+      }),
+    },
+  ]);
 }
 
 /** Go AbortedError — retryable conflict (e.g. an in-flight dedupe claim). */