@stigmer/server 3.38.2 → 3.39.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/server",
-  "version": "3.38.2",
+  "version": "3.39.0",
   "description": "The Stigmer OSS control plane as a composable library: composeServer, the extension registry and the driver seams a composition builds on. The self-contained deployable of the same server is @stigmer/server-slim.",
   "license": "Apache-2.0",
   "type": "module",
@@ -63,11 +63,11 @@
     "@connectrpc/connect-node": "^2.0.0",
     "@kubernetes/client-node": "2.0.0",
     "@opentelemetry/api": "^1.9.0",
-    "@stigmer/outbound": "3.38.2",
-    "@stigmer/plugin-package": "3.38.2",
-    "@stigmer/protos": "3.38.2",
-    "@stigmer/temporal-codecs": "3.38.2",
-    "@stigmer/zip-structure": "3.38.2",
+    "@stigmer/outbound": "3.39.0",
+    "@stigmer/plugin-package": "3.39.0",
+    "@stigmer/protos": "3.39.0",
+    "@stigmer/temporal-codecs": "3.39.0",
+    "@stigmer/zip-structure": "3.39.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/client": "1.16.2",
     "@temporalio/common": "1.16.2",

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

@@ -0,0 +1,105 @@
+/**
+ * Pins the store-fault contract of the agent's visibility-update load: a
+ * typed ResourceNotFoundError answers NotFound with the domain's pinned copy
+ * (`agent not found: <id>`), and any other store failure is an
+ * infrastructure fault answered as a sanitized Internal, never a NotFound
+ * that tells a client the agent does not exist (stigmer/stigmer#1345).
+ *
+ * The surface is updateVisibility, reached through the registered handler on
+ * an in-process router. The composed suites reach only a real store, which
+ * cannot fail selectively, so it runs here against a store whose read throws.
+ * The default-instance applier is untouchable: a load that fails must stop
+ * the call before anything past it runs.
+ *
+ * Out of scope: the NotFound copy itself (wire contract) and getByAgent's
+ * empty-list answer on an agent-read fault in the channel and share domains
+ * (stigmer/stigmer#1375).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import {
+  errorOf,
+  failingStore,
+  untouchable,
+} from "../../../pipeline/__tests__/support.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+
+import { registerAgentServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const AGENT_ID = "agt_storefault";
+
+const NOT_FOUND_COPY = `agent not found: ${AGENT_ID}`;
+const LOAD_FAULT_COPY = "failed to load agent";
+
+const MISSING = (): Error => new ResourceNotFoundError(`agent/${AGENT_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+/**
+ * The registered handlers on an in-process router: the verifier chain stamps
+ * the trusted-local caller and the apiresource interceptor the kind, then
+ * Authorize and ValidateProto run and the load is the first step that reads
+ * the store.
+ */
+function agentCommand(store: Store): Client<typeof AgentCommandController> {
+  const transport = createRouterTransport(
+    (router) => {
+      registerAgentServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        agentInstanceApplier: untouchable("agentInstanceApplier"),
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(AgentCommandController, transport);
+}
+
+describe("updateVisibility — LoadAgentForVisibilityUpdate", () => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() =>
+      agentCommand(store).updateVisibility({
+        resourceId: AGENT_ID,
+        visibility: ApiResourceVisibility.visibility_private,
+      }),
+    );
+  }
+
+  it("a missing agent answers NotFound with the domain's copy", async () => {
+    const error = await surfaceError(failingStore(MISSING()));
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await surfaceError(failingStore(LOCKED()));
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
+  });
+});

package/src/domain/agent/controller.ts

@@ -8,8 +8,8 @@
  * agent to serve: a session with no agent runs the built-in assistant.
  *
  * Pipeline per RPC mirrors the Go step chains character-for-character.
- * Proven by agent.conformance.test.ts (CONFORMANCE_TARGET=local) and
- * __tests__/agent.test.ts.
+ * Proven by agent.conformance.test.ts (CONFORMANCE_TARGET=local),
+ * __tests__/agent.test.ts and __tests__/store-faults.test.ts.
  *
  * Versus Stigmer Cloud, OSS excludes the Authorize, CreateIamPolicies, and
  * Publish steps (no multi-tenant auth, IAM/FGA, or event publishing here).
@@ -91,6 +91,7 @@ import {
   newValidateVisibilityStep,
   newValidateVisibilityUpdateStep,
 } from "../../pipeline/steps/validate-visibility.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import { agentSearchExtractor } from "./search-extractor.js";
 import {
@@ -382,7 +383,7 @@ async function updateVisibility(
   return reqCtx.get(UPDATE_VISIBILITY_AGENT_KEY) as Agent;
 }
 
-/** Loads the agent by resource_id; ANY load failure → NotFound. */
+/** Loads the agent by resource_id; a missing one answers NotFound, a store fault Internal. */
 function newLoadAgentForVisibilityUpdateStep(
   store: Store,
 ): PipelineStep<UpdateVisibilityDesc> {
@@ -397,8 +398,11 @@ function newLoadAgentForVisibilityUpdateStep(
           input.resourceId,
           AgentSchema,
         );
-      } catch {
-        throw notFoundError("agent", input.resourceId);
+      } catch (error) {
+        if (error instanceof ResourceNotFoundError) {
+          throw notFoundError("agent", input.resourceId);
+        }
+        throw internalError(error, "failed to load agent");
       }
       ctx.set(UPDATE_VISIBILITY_AGENT_KEY, agent);
     },

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

@@ -0,0 +1,126 @@
+/**
+ * Pins the store-fault contract of the install lane's channel load, which
+ * initiateInstall and completeInstall share: a typed ResourceNotFoundError
+ * answers NotFound with the domain's pinned copy
+ * (`AgentChannel not found: <id>`), and any other store failure is an
+ * infrastructure fault answered as a sanitized Internal, never a NotFound
+ * that tells a client the channel does not exist (stigmer/stigmer#1345).
+ *
+ * Both surfaces are reached through the registered handler on an in-process
+ * router. The composed suites reach only a real store, which cannot fail
+ * selectively, so each runs here against a store whose read throws. The
+ * channel runtime and the model registry are untouchable: the load comes
+ * before authorization and before the runtime, so a load that fails must
+ * stop the call before either.
+ *
+ * Out of scope: the NotFound copy itself (wire contract, pinned by
+ * agentchannel.test.ts and the agentchannel conformance suite) and
+ * getByAgent's empty-list answer on an agent-read fault
+ * (stigmer/stigmer#1375).
+ */
+import type { Client, ConnectError } from "@connectrpc/connect";
+import { Code, createClient, createRouterTransport } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { AgentChannelCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/command_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { createApiResourceInterceptor } from "../../../pipeline/interceptors/apiresource.js";
+import { createVerifierChainInterceptor } from "../../../pipeline/interceptors/auth.js";
+import {
+  errorOf,
+  failingStore,
+  untouchable,
+} from "../../../pipeline/__tests__/support.js";
+import { newPermissiveSingleTeamAuthorizer } from "../../../pipeline/steps/authorize.js";
+import { ResourceNotFoundError } from "../../../store/interface.js";
+import type { Store } from "../../../store/interface.js";
+
+import type { ChannelRuntime } from "../channel-runtime.js";
+import { registerAgentChannelServices } from "../controller.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const CHANNEL_ID = "ach_storefault";
+
+const NOT_FOUND_COPY = `AgentChannel not found: ${CHANNEL_ID}`;
+const LOAD_FAULT_COPY = "failed to load agent channel";
+
+const MISSING = (): Error =>
+  new ResourceNotFoundError(`agent_channel/${CHANNEL_ID}`);
+const LOCKED = (): Error => new Error("SQLITE_BUSY: database is locked");
+
+type ChannelCommand = Client<typeof AgentChannelCommandController>;
+
+/**
+ * The registered handlers on an in-process router: the verifier chain stamps
+ * the trusted-local caller and the apiresource interceptor the kind the
+ * install load reads; the load is the first thing either handler does.
+ */
+function channelCommand(store: Store): ChannelCommand {
+  const transport = createRouterTransport(
+    (router) => {
+      registerAgentChannelServices(router, {
+        store,
+        logger: silentLogger,
+        authorizer: newPermissiveSingleTeamAuthorizer(),
+        authorizationLifecycle: undefined,
+        modelRegistry: untouchable("modelRegistry"),
+        channelRuntime: untouchable<ChannelRuntime>("channelRuntime"),
+        listReadScope: undefined,
+      });
+    },
+    {
+      router: {
+        interceptors: [
+          createVerifierChainInterceptor([], [], silentLogger),
+          createApiResourceInterceptor(),
+        ],
+      },
+    },
+  );
+  return createClient(AgentChannelCommandController, transport);
+}
+
+/** Each surface with the input its proto requires. */
+const SURFACES: ReadonlyArray<
+  readonly [string, (command: ChannelCommand) => Promise<unknown>]
+> = [
+  [
+    "initiateInstall — the install load",
+    (command) => command.initiateInstall({ resourceId: CHANNEL_ID }),
+  ],
+  [
+    "completeInstall — the install load",
+    (command) =>
+      command.completeInstall({
+        resourceId: CHANNEL_ID,
+        state: "install-state",
+        code: "provider-code",
+      }),
+  ],
+];
+
+describe.each(SURFACES)("%s", (_name, call) => {
+  function surfaceError(store: Store): Promise<ConnectError> {
+    return errorOf(() => call(channelCommand(store)));
+  }
+
+  it("a missing channel answers NotFound with the domain's copy", async () => {
+    const error = await surfaceError(failingStore(MISSING()));
+
+    expect(error.code).toBe(Code.NotFound);
+    expect(error.rawMessage).toBe(NOT_FOUND_COPY);
+  });
+
+  it("any other store failure answers a sanitized Internal", async () => {
+    const error = await surfaceError(failingStore(LOCKED()));
+
+    expect(error.code).toBe(Code.Internal);
+    expect(error.rawMessage).toBe(LOAD_FAULT_COPY);
+  });
+});

package/src/domain/agentchannel/controller.ts

@@ -23,8 +23,8 @@
  * (only same-org shares are) — a dangling channel is tolerated because
  * OSS has no serving runtime and cloud fails closed elsewhere.
  *
- * Proven by agentchannel.conformance.test.ts (CONFORMANCE_TARGET=local)
- * and __tests__/agentchannel.test.ts.
+ * Proven by agentchannel.conformance.test.ts (CONFORMANCE_TARGET=local),
+ * __tests__/agentchannel.test.ts and __tests__/store-faults.test.ts.
  */
 import type { ConnectRouter, HandlerContext } from "@connectrpc/connect";
 import { create, fromBinary } from "@bufbuild/protobuf";
@@ -108,6 +108,7 @@ import { newPersistStep } from "../../pipeline/steps/persist.js";
 import { newResolveSlugStep } from "../../pipeline/steps/slug.js";
 import { newValidateProtoStep } from "../../pipeline/steps/validation.js";
 import { newValidateVisibilityStep } from "../../pipeline/steps/validate-visibility.js";
+import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
 import type { ModelCatalogProvider } from "../workflow/registry/model-catalog-provider.js";
 import type { ChannelRuntime } from "./channel-runtime.js";
@@ -395,9 +396,10 @@ async function completeInstall(
 }
 
 /**
- * Loads the install target — cloud's LoadChannel NOT_FOUND, verbatim.
- * Returns the loaded channel so a composed runtime receives it without a
- * second load (the load-then-X contract stays OSS-owned).
+ * Loads the install target — cloud's LoadChannel NOT_FOUND, verbatim, for
+ * a missing channel; a store fault answers Internal. Returns the loaded
+ * channel so a composed runtime receives it without a second load (the
+ * load-then-X contract stays OSS-owned).
  */
 async function loadChannelForInstall(
   deps: AgentChannelControllerDeps,
@@ -410,8 +412,11 @@ async function loadChannelForInstall(
       resourceId,
       AgentChannelSchema,
     );
-  } catch {
-    throw notFoundError("AgentChannel", resourceId);
+  } catch (error) {
+    if (error instanceof ResourceNotFoundError) {
+      throw notFoundError("AgentChannel", resourceId);
+    }
+    throw internalError(error, "failed to load agent channel");
   }
 }
 

package/src/domain/agentexecution/__tests__/run-gate.test.ts

@@ -7,7 +7,10 @@
  * denial leaves no execution row AND creates no default instance — the
  * "no side effect precedes the check" property; (3) the gate precedes the
  * engine gate: an ALLOWED create on this engineless server answers the
- * engine's UNAVAILABLE, a DENIED one PERMISSION_DENIED. The authorizer
+ * engine's UNAVAILABLE, a DENIED one PERMISSION_DENIED; (4) the
+ * thinking-mode validation, which may read the stored session, runs behind
+ * the gate (stigmer/stigmer#1280): a DENIED create with an invalid thinking
+ * mode answers PERMISSION_DENIED, an ALLOWED one INVALID_ARGUMENT. The authorizer
  * under test answers only run-gate checks (runGateOnlyAuthorizer), so every
  * refusal here is the run gate's and nobody else's.
  */
@@ -25,6 +28,7 @@ import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb"
 import { AgentExecutionCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/command_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
 import { IamPermission } from "@stigmer/protos/ai/stigmer/iam/v1/enum_pb";
+import { ThinkingMode } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/enum_pb";
 
 import { loadConfig } from "../../../boot/config.js";
 import { composeServer } from "../../../boot/compose.js";
@@ -134,6 +138,7 @@ function createInput(spec: {
   agentId?: string;
   sessionId?: string;
   sessionSpec?: { agentInstanceId: string };
+  executionConfig?: { modelName?: string; thinkingMode?: ThinkingMode };
 }) {
   return {
     apiVersion: API_VERSION,
@@ -242,4 +247,40 @@ describe("agent-execution-create run gate (composed server)", () => {
     expect(err.rawMessage).toBe(ENGINE_UNAVAILABLE_MESSAGE);
     expect(gate.runGateChecks.map((c) => c.resourceId)).toEqual([agentId]);
   });
+
+  it("thinking-mode validation runs behind the gate: a denied caller learns nothing about the session", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+
+    const err = await captureError(() =>
+      command.create(
+        createInput({
+          sessionId: "ses_01someoneelses",
+          executionConfig: { modelName: "composer-2.5", thinkingMode: ThinkingMode.ENABLED },
+        }),
+      ),
+    );
+
+    expect(err.code).toBe(Code.PermissionDenied);
+    expect(err.rawMessage).toBe(addExecutionToSessionDeniedMessage("ses_01someoneelses"));
+  });
+
+  it("an allowed create with an invalid thinking mode is refused by the validation, before the engine gate", async () => {
+    decision = { kind: "allow" };
+    const agentId = await createAgentWithoutDefaultInstance("Thinking agent");
+    const instancesBefore = await count(ApiResourceKind.agent_instance);
+
+    const err = await captureError(() =>
+      command.create(
+        createInput({
+          agentId,
+          executionConfig: { modelName: "composer-2.5", thinkingMode: ThinkingMode.ENABLED },
+        }),
+      ),
+    );
+
+    expect(err.code).toBe(Code.InvalidArgument);
+    expect(err.rawMessage).toContain("no thinking capability");
+    expect(await count(ApiResourceKind.agent_instance)).toBe(instancesBefore);
+  });
 });

package/src/domain/agentexecution/__tests__/update-status.test.ts

@@ -8,7 +8,9 @@
  * Also pins the platform-row rules (platform-rows.ts, stigmer#980): a
  * platform marker write is appended to the transcript and never replaces
  * it, idempotently, and a PAUSED or CANCELLED execution's stop row stays
- * last across the runner's late writes, whatever order they land in.
+ * last across the runner's late writes, whatever order they land in; and a
+ * paused execution's phase moves only on the platform's own write
+ * (stigmer#1370), so the runner's straggler streaming cannot un-pause it.
  * These exercise applyUpdateStatusMerge directly on a clone — mirroring
  * the freshly-loaded resource the merge mutates in place inside the
  * updateResource write lock.
@@ -37,6 +39,7 @@ import { createLogger } from "../../../boot/logger.js";
 import { findToolCallInExecution } from "../submit-approval.js";
 import { CANCEL_STOP_ROW, PAUSE_STOP_ROW } from "../platform-rows.js";
 import { applyUpdateStatusMerge } from "../update-status.js";
+import type { StatusWriter } from "../update-status.js";
 
 const silentLogger = createLogger({
   level: "error",
@@ -51,13 +54,14 @@ const silentLogger = createLogger({
 function runBuildStep(
   existing: AgentExecution,
   incoming: MessageInitShape<typeof AgentExecutionStatusSchema>,
+  writer: StatusWriter = "wire",
 ): AgentExecution {
   const input = create(AgentExecutionUpdateStatusInputSchema, {
     executionId: existing.metadata?.id ?? "",
     status: incoming,
   });
   const merged = clone(AgentExecutionSchema, existing);
-  applyUpdateStatusMerge(merged, input, silentLogger);
+  applyUpdateStatusMerge(merged, input, silentLogger, writer);
   return merged;
 }
 
@@ -584,3 +588,55 @@ describe("platform rows (stigmer#980)", () => {
     });
   });
 });
+
+describe("a paused execution stays paused until Resume (stigmer#1370)", () => {
+  function pausedWith(...contents: string[]): AgentExecution {
+    return create(AgentExecutionSchema, {
+      metadata: { id: "exec-paused", name: "exec-paused" },
+      spec: {},
+      status: {
+        phase: ExecutionPhase.EXECUTION_PAUSED,
+        messages: [
+          ...contents.map((content) => ({ type: MessageType.MESSAGE_AI, content })),
+          { type: MessageType.MESSAGE_SYSTEM, content: PAUSE_STOP_ROW },
+        ],
+      },
+    });
+  }
+  const contentsOf = (e: AgentExecution) => (e.status?.messages ?? []).map((m) => m.content);
+
+  it("keeps PAUSED across the runner's straggler streaming write, and merges its text beneath the pause row", () => {
+    // The Pause RPC and the workflow's row landed; the runner learns of the
+    // pause on a later heartbeat and keeps streaming IN_PROGRESS writes that
+    // carry its growing transcript without the row.
+    const merged = runBuildStep(pausedWith("The press, part"), {
+      phase: ExecutionPhase.EXECUTION_IN_PROGRESS,
+      messages: [{ type: MessageType.MESSAGE_AI, content: "The press, part one and two" }],
+    });
+    expect(merged.status?.phase, "a wire write cannot un-pause").toBe(ExecutionPhase.EXECUTION_PAUSED);
+    expect(contentsOf(merged)).toEqual(["The press, part one and two", PAUSE_STOP_ROW]);
+  });
+
+  it("keeps PAUSED against a wire phase-only IN_PROGRESS write", () => {
+    const merged = runBuildStep(pausedWith("a1"), { phase: ExecutionPhase.EXECUTION_IN_PROGRESS });
+    expect(merged.status?.phase).toBe(ExecutionPhase.EXECUTION_PAUSED);
+  });
+
+  it("lets the platform's own write move a paused execution (the workflow's resume heal)", () => {
+    const merged = runBuildStep(
+      pausedWith("a1"),
+      { phase: ExecutionPhase.EXECUTION_IN_PROGRESS },
+      "platform",
+    );
+    expect(merged.status?.phase).toBe(ExecutionPhase.EXECUTION_IN_PROGRESS);
+    expect(contentsOf(merged)).toEqual(["a1", PAUSE_STOP_ROW]);
+  });
+
+  it("leaves a wire write on a running execution as it was (the latch is PAUSED's alone)", () => {
+    const merged = runBuildStep(existingWith(ExecutionPhase.EXECUTION_IN_PROGRESS, "m1"), {
+      phase: ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL,
+      messages: [{ content: "m1" }],
+    });
+    expect(merged.status?.phase).toBe(ExecutionPhase.EXECUTION_WAITING_FOR_APPROVAL);
+  });
+});