@stigmer/server 3.20.0 → 3.22.0

package/src/extensions/__tests__/composed-support.ts

@@ -23,7 +23,7 @@
  */
 import path from "node:path";
 
-import type { DescService } from "@bufbuild/protobuf";
+import type { DescMethod, DescService } from "@bufbuild/protobuf";
 import type {
   ConnectRouter,
   Interceptor,
@@ -94,11 +94,30 @@ export function bearer(token: string): Interceptor {
 export function servedServices(
   routes: (router: ConnectRouter) => void,
 ): DescService[] {
-  const served: DescService[] = [];
+  return servedRegistrations(routes).map((r) => r.service);
+}
+
+/** One `router.service(desc, implementation)` registration, as replayed. */
+export interface ServedRegistration {
+  readonly service: DescService;
+  readonly implementation: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * The registrations themselves, with each service's implementation map,
+ * for a reader that must know which of a service's methods are actually
+ * served: a partially implemented service (a method registered only when
+ * a composed capability carries it) lists the method on its descriptor
+ * and omits it from the map, and ConnectRPC answers UNIMPLEMENTED for it.
+ */
+export function servedRegistrations(
+  routes: (router: ConnectRouter) => void,
+): ServedRegistration[] {
+  const served: ServedRegistration[] = [];
   const recorder = {
     handlers: [],
-    service(desc: DescService) {
-      served.push(desc);
+    service(desc: DescService, implementation: Record<string, unknown>) {
+      served.push({ service: desc, implementation });
       return recorder;
     },
     rpc() {
@@ -109,6 +128,21 @@ export function servedServices(
   return served;
 }
 
+/** The methods a composed server actually serves: on a registered service AND in its implementation map. */
+export function servedMethods(
+  routes: (router: ConnectRouter) => void,
+): DescMethod[] {
+  const methods: DescMethod[] = [];
+  for (const { service, implementation } of servedRegistrations(routes)) {
+    for (const method of service.methods) {
+      if (method.localName in implementation) {
+        methods.push(method);
+      }
+    }
+  }
+  return methods;
+}
+
 /** A gRPC transport to the composed server on `port`, presenting `token` when given. */
 export function transportFor(port: number, token?: string): Transport {
   return createGrpcTransport({

package/src/extensions/__tests__/identity.test.ts

@@ -6,10 +6,20 @@
  * `create` RPC's admission rule (2a A7) and the three IamPolicy system
  * RPCs' (Q-OR-7). A wire `user`, `runner` or a composition's own class
  * (guest) is never one.
+ *
+ * Also pins `isServerComposedRequest`, the narrower predicate the label
+ * guard, the memory-capture gate, the execution-context create check and
+ * the default-instance arm of the instance creates share: `internal` or an
+ * in-process origin, and never a wire `machine` account — the one row
+ * where the two predicates part, pinned so a step trusting server-composed
+ * state can never be widened to the wire by picking the wrong one.
  */
 import { describe, expect, it } from "vitest";
 
-import { isPlatformPipelineCaller } from "../identity.js";
+import {
+  isPlatformPipelineCaller,
+  isServerComposedRequest,
+} from "../identity.js";
 import type { CallerIdentity } from "../identity.js";
 
 function caller(fields: Partial<CallerIdentity>): CallerIdentity {
@@ -60,3 +70,36 @@ describe("isPlatformPipelineCaller", () => {
     );
   });
 });
+
+describe("isServerComposedRequest", () => {
+  it("is true for the internal class and for any identity that entered in-process", () => {
+    expect(isServerComposedRequest(caller({ callerClass: "internal" }))).toBe(
+      true,
+    );
+    expect(
+      isServerComposedRequest(
+        caller({ callerClass: "user", origin: "in-process" }),
+      ),
+    ).toBe(true);
+    expect(
+      isServerComposedRequest(
+        caller({ callerClass: "channel", origin: "in-process" }),
+      ),
+    ).toBe(true);
+  });
+
+  it("is false for every wire caller, the machine class included — the row where it parts from isPlatformPipelineCaller", () => {
+    const wireMachine = caller({ callerClass: "machine" });
+    expect(isServerComposedRequest(wireMachine)).toBe(false);
+    expect(isPlatformPipelineCaller(wireMachine)).toBe(true);
+    expect(isServerComposedRequest(caller({ callerClass: "user" }))).toBe(
+      false,
+    );
+    expect(
+      isServerComposedRequest(caller({ callerClass: "user", origin: "wire" })),
+    ).toBe(false);
+    expect(isServerComposedRequest(caller({ callerClass: "runner" }))).toBe(
+      false,
+    );
+  });
+});

package/src/extensions/__tests__/list-read-scope-composed.test.ts

@@ -12,7 +12,14 @@
  *   - search (enumeration verb feeding the engine allowlist, and the
  *     crossOrgPublic bypass where FGA is never consulted — lane 21),
  *   - the OUTAGE arm: a throwing scope answers the sanitized INTERNAL,
- *     never an empty (or full!) list.
+ *     never an empty (or full!) list;
+ *   - the SERVER'S OWN reads over `inProcessTransport` (stigmer#1207):
+ *     the bare in-process call is stamped `internal` and the helper
+ *     answers it before the scope — agentexecution.listBySession (the
+ *     lane every server-internal reader of a session's turns rides) and
+ *     workflowexecution.list with the org arm still applied; a caller
+ *     PROPAGATED through the in-process header keeps its class and is
+ *     narrowed exactly like the wire.
  *
  * Per-lane logic beyond the wiring is pinned in the helper matrix
  * (list-read-scope.test.ts), the summaries suite, and the store-contract
@@ -31,6 +38,8 @@ import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
 
 import { ActivityQueryController } from "@stigmer/protos/ai/stigmer/activity/v1/query_pb";
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+import { AgentExecutionQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/query_pb";
 import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import { SessionQueryController } from "@stigmer/protos/ai/stigmer/agentic/session/v1/query_pb";
 import { WorkflowExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/workflowexecution/v1/api_pb";
@@ -44,6 +53,11 @@ import { loadConfig } from "../../boot/config.js";
 import { composeServer } from "../../boot/compose.js";
 import type { ComposedServer } from "../../boot/compose.js";
 import { createLogger } from "../../boot/logger.js";
+import { testCallerIdentity } from "../../pipeline/__tests__/support.js";
+import {
+  IN_PROCESS_CALLER_HEADER,
+  encodeInProcessCaller,
+} from "../../pipeline/interceptors/auth.js";
 import type { ListReadScope } from "../list-read-scope.js";
 import type { ServerExtension } from "../registry.js";
 
@@ -133,6 +147,27 @@ describe("list read scope (composed server, fake scope)", () => {
         }),
       );
     }
+    // Two turns of one session — the rows a server-internal reader of a
+    // conversation's executions asks listBySession for.
+    for (const id of ["aex_turn_1", "aex_turn_2"]) {
+      await server.store.saveResource(
+        ApiResourceKind.agent_execution,
+        id,
+        AgentExecutionSchema,
+        create(AgentExecutionSchema, {
+          apiVersion: "agentic.stigmer.ai/v1",
+          kind: "AgentExecution",
+          metadata: { id, name: id, org: "acme" },
+          spec: { sessionId: "ses_mine" },
+          status: {
+            audit: {
+              specAudit: { createdAt: { seconds: 1_700_000_000n } },
+              statusAudit: { updatedAt: { seconds: 1_700_000_000n } },
+            },
+          },
+        }),
+      );
+    }
     for (const [id, org] of [
       ["wfe_mine", "acme"],
       ["wfe_other_org", "rival"],
@@ -273,4 +308,55 @@ describe("list read scope (composed server, fake scope)", () => {
     const list = await query.list({});
     expect(list.entries).toEqual([]);
   });
+
+  describe("the server's own reads over the in-process transport (stigmer#1207)", () => {
+    it("agentexecution.listBySession, bare: every turn of the session, the scope never asked", async () => {
+      // The scope would hide everything if it were asked.
+      allowed = new Set();
+      const query = createClient(
+        AgentExecutionQueryController,
+        server.inProcessTransport,
+      );
+      const turns = await query.listBySession({ sessionId: "ses_mine" });
+      expect(turns.entries.map((e) => e.metadata?.id).sort()).toEqual([
+        "aex_turn_1",
+        "aex_turn_2",
+      ]);
+      expect(seenKinds).toEqual([]);
+    });
+
+    it("a caller propagated through the in-process header keeps its class and is narrowed like the wire", async () => {
+      allowed = new Set(["aex_turn_2"]);
+      const query = createClient(
+        AgentExecutionQueryController,
+        server.inProcessTransport,
+      );
+      const turns = await query.listBySession(
+        { sessionId: "ses_mine" },
+        {
+          headers: {
+            [IN_PROCESS_CALLER_HEADER]: encodeInProcessCaller(
+              testCallerIdentity({ identityId: "alice" }),
+            ),
+          },
+        },
+      );
+      expect(turns.entries.map((e) => e.metadata?.id)).toEqual(["aex_turn_2"]);
+      expect(seenKinds).toEqual([ApiResourceKind.agent_execution]);
+    });
+
+    it("workflowexecution.list, bare: the request's org predicate still applies, the scope never asked", async () => {
+      allowed = new Set();
+      const query = createClient(
+        WorkflowExecutionQueryController,
+        server.inProcessTransport,
+      );
+      const acme = await query.list({ org: "acme" });
+      expect(acme.entries.map((e) => e.metadata?.id).sort()).toEqual([
+        "wfe_foreign",
+        "wfe_mine",
+      ]);
+      expect(seenKinds).toEqual([]);
+    });
+  });
 });

package/src/extensions/__tests__/list-read-scope.test.ts

@@ -12,6 +12,11 @@
  *     20260913.04 T02 the scope is the last per-row predicate, so it is
  *     offered the org's rows and never the kind's — the same result set,
  *     a fraction of the candidates);
+ *   - the `internal` class — the server acting as itself — gets the
+ *     org-narrowed rows and the scope is never asked (the Authorize
+ *     step's trust-domain rule on a list answer, stigmer#1207); the rule
+ *     is class-only, so a caller PROPAGATED through the in-process
+ *     transport (its own class, origin in-process) is still narrowed;
  *   - the candidates carry {id, org, labels} — the driver's guest
  *     cookie rule keys on labels — and the row's AUTHORIZATION FACTS
  *     (creator stamp, visibility level, every parent link), read by the
@@ -160,6 +165,64 @@ describe("restrictListByReadScope", () => {
     ]);
   });
 
+  describe("the internal class — the server acting as itself (stigmer#1207)", () => {
+    /** A scope that must never be reached: any call is the failure under test. */
+    const neverAsked: ListReadScope = {
+      authorizedResourceIds: () =>
+        Promise.reject(new Error("the scope was asked for the internal class")),
+      restrictListEntries: () =>
+        Promise.reject(new Error("the scope was asked for the internal class")),
+    };
+    const internal = testCallerIdentity({
+      identityId: "system",
+      callerClass: "internal",
+      origin: "in-process",
+    });
+
+    it("gets the org-narrowed rows in the lane's order; the scope is never asked", async () => {
+      const withOrg = await restrictListByReadScope(
+        neverAsked,
+        internal,
+        ApiResourceKind.session,
+        rows,
+        "acme",
+      );
+      // The request's org predicate still applies — it is the request's,
+      // not the caller's; only the caller predicate is skipped.
+      expect(withOrg.map((r) => r.metadata.id)).toEqual(["ses_a", "ses_b"]);
+      const blankOrg = await restrictListByReadScope(
+        neverAsked,
+        internal,
+        ApiResourceKind.session,
+        rows,
+        "",
+      );
+      expect(blankOrg.map((r) => r.metadata.id)).toEqual([
+        "ses_a",
+        "ses_b",
+        "ses_c",
+      ]);
+      // A fresh array either way, as every arm of the helper returns.
+      expect(blankOrg).not.toBe(rows);
+    });
+
+    it("the rule is class-only: a caller propagated through the in-process transport keeps its class and is still narrowed", async () => {
+      const propagated = testCallerIdentity({
+        identityId: "alice",
+        callerClass: "user",
+        origin: "in-process",
+      });
+      const kept = await restrictListByReadScope(
+        scopeKeeping(["ses_c"]),
+        propagated,
+        ApiResourceKind.session,
+        rows,
+        "",
+      );
+      expect(kept.map((r) => r.metadata.id)).toEqual(["ses_c"]);
+    });
+  });
+
   it("an empty kept set is a real answer — the empty list", async () => {
     const kept = await restrictListByReadScope(
       scopeKeeping([]),

package/src/extensions/identity.ts

@@ -112,9 +112,27 @@ export interface IdentityVerifier {
  * rule is load-bearing in open source.
  */
 export function isPlatformPipelineCaller(caller: CallerIdentity): boolean {
-  return (
-    caller.callerClass === "machine" ||
-    caller.callerClass === "internal" ||
-    caller.origin === "in-process"
-  );
+  return caller.callerClass === "machine" || isServerComposedRequest(caller);
+}
+
+/**
+ * Whether the request `caller` arrived on was composed by the server's own
+ * code rather than presented on the wire: the `internal` class (the server
+ * acting as itself) or ANY identity that entered through the in-process
+ * transport (a propagated person the server is building a request for,
+ * such as the default-instance self-heal that creates as the run's human
+ * for attribution). The serving chassis strips the propagation header, so
+ * the wire cannot claim this.
+ *
+ * This is the trust arm the label guard, the memory-capture gate and the
+ * execution-context create check share: what a server-composed request
+ * carries was decided by the service code that built it, and the
+ * entry-point request already passed its own gate. It is NARROWER than
+ * `isPlatformPipelineCaller`: a wire `machine` account is one of the
+ * platform's pipelines but its request is still the wire's, so a step
+ * that trusts server-composed state (a reserved label, a default
+ * instance's provenance) must key on this predicate and never on that one.
+ */
+export function isServerComposedRequest(caller: CallerIdentity): boolean {
+  return caller.callerClass === "internal" || caller.origin === "in-process";
 }

package/src/extensions/list-read-scope.ts

@@ -48,11 +48,27 @@
  *     authorization-backend outage surfaces as the pipeline's sanitized
  *     INTERNAL, exactly the Java baseline (DD-007: unavailable is never
  *     softened).
- *   - The scope receives whatever identity the call carries, including
- *     the in-process `internal` class — the driver owns that arm's
- *     semantics (the Java baseline propagates the original caller
- *     through in-process calls, so a composed driver normally never
- *     sees `internal` on these lanes).
+ *   - THE `internal` CLASS IS ANSWERED HERE, NEVER OFFERED TO
+ *     `restrictListEntries`. The server acting as itself over the
+ *     in-process transport (boot/inprocess.ts mints the class; nothing
+ *     else can) is the server's own trust domain, on list lanes exactly
+ *     as on the Authorize step, which returns for the class before any
+ *     Authorizer is asked (pipeline/steps/authorize.ts). The helper
+ *     below returns the org-narrowed rows for that class before the
+ *     scope is consulted. The rule is class-only, like the step's: a
+ *     caller PROPAGATED through the in-process header keeps its own
+ *     class and stays scoped. Why here and not in a driver: a driver
+ *     answering "every offered id" for the class must be written once
+ *     per edition and is a silent short list the day one edition
+ *     forgets (stigmer#1207: a composed driver scoped the class and
+ *     every server-internal list read came back empty — the
+ *     personal-environment reads at execution-context creation and MCP
+ *     connect in this repository, and a composition's own in-process
+ *     readers of a session's executions).
+ *     The enumeration verb is a wire caller's verb: no in-process edge
+ *     reaches `authorizedResourceIds`, and only a scanning driver can
+ *     say "all", so that verb's internal arm stays the driver's and is
+ *     stated in its doc below.
  *   - THE SCOPE IS THE LAST PER-ROW PREDICATE IN A LANE (stigmer-cloud
  *     20260913.04 T02, Q-LB-11). Every request predicate a lane applies
  *     — the request's org, a phase, labels, a parent id, filter criteria
@@ -157,6 +173,13 @@ export interface ListReadScope {
    * answer — consumers map it to their lane's empty shape without
    * touching the store. A scope may throw on a kind it was never ruled
    * to serve (a consumer bug by contract).
+   *
+   * The `internal` class CAN reach this verb (no helper stands between a
+   * consumer and it), and the driver owns that arm: a scanning driver
+   * answers every id of the kind, an engine-backed one answers what its
+   * engine holds for the class. No in-process edge reaches an
+   * enumeration lane today, so the two answers have never met a caller;
+   * a consumer that adds one reads this line first.
    */
   authorizedResourceIds(
     caller: CallerIdentity,
@@ -168,6 +191,12 @@ export interface ListReadScope {
    * baseline: the authorized-ids intersection plus the guest
    * cookie-label rule where the lane carries it). The result must be a
    * subset of the offered ids — a scope only narrows.
+   *
+   * `caller` is never the `internal` class: `restrictListByReadScope`,
+   * the one consumption idiom, answers that class before any driver is
+   * asked (the header's contract line). A driver that is offered it has
+   * been reached around the idiom and should refuse loudly rather than
+   * evaluate the server as a person (the built-in driver does).
    */
   restrictListEntries(
     caller: CallerIdentity,
@@ -209,8 +238,13 @@ export interface ScopedListResource {
  *     permission-bounded across orgs, verified per lane in the entry's
  *     census — lanes Java does not org-narrow pass ""), then to the kept
  *     ids. The same set either way (both are per-row predicates); the
- *     order is the header's second-to-last contract line: the scope sees
- *     the org's rows, not the kind's;
+ *     order is the header's contract line: the scope sees the org's
+ *     rows, not the kind's;
+ *   - scope composed, caller `internal` → the org-narrowed rows, the
+ *     scope never asked and no candidate built (the header's contract
+ *     line). The org predicate is the REQUEST's, not the caller's, so
+ *     the server's own read of a cross-org lane still honours the org
+ *     it asked for; only the caller predicate is skipped;
  *   - every candidate carries the row's authorization facts, and the
  *     candidates of a kind whose authorization is its parent's name that
  *     parent again as `authorizationParent` — one of the facts' parent
@@ -231,6 +265,12 @@ export async function restrictListByReadScope<T extends ScopedListResource>(
     requestOrg === ""
       ? resources
       : resources.filter((resource) => resource.metadata?.org === requestOrg);
+  // The server acting as itself: the trust-domain rule of the Authorize
+  // step, applied to a list answer — the caller predicate is skipped, the
+  // request's org predicate above is not (the header's contract line).
+  if (caller.callerClass === "internal") {
+    return [...offered];
+  }
   const parentOf = authorizationParentReader(kind);
   const entries: ListEntryMeta[] = offered.map((resource) => {
     const entry: ListEntryMeta = {

package/src/pipeline/apiresource-labels.ts

@@ -23,8 +23,8 @@ import type { ApiResourceMetadata } from "@stigmer/protos/ai/stigmer/commons/api
 
 /**
  * The platform-reserved label key namespace. Keys under this prefix carry
- * platform semantics (default-agent resolution, personal-environment
- * uniqueness, default-instance marking) and are written by the server —
+ * platform semantics (personal-environment uniqueness, default-instance
+ * marking, plugin membership and lineage) and are written by the server —
  * never introduced by ordinary client requests on the cloud edition.
  */
 export const RESERVED_LABEL_PREFIX = "stigmer.ai/";

package/src/pipeline/errors.ts

@@ -100,8 +100,8 @@ export function grpcCodeName(code: Code): string {
  * errors.As branch keeps the INNER code but rewrites the message to the
  * full wrapped text — and the inner client error's Error() renders as
  * `rpc error: code = <CodeName> desc = <message>`. Byte-parity with Go on
- * the two arms that hit this (agent create's CreateDefaultInstance,
- * session create's ResolveDefaultAgentInstance). The transport-formatting
+ * the arms that hit this (agent create's CreateDefaultInstance, agent
+ * execution create's default-instance and session bootstrap). The transport-formatting
  * leak is filed as stigmer/stigmer#852 for a both-editions post-cutover
  * fix; until then this shim IS the wire contract.
  *