@stigmer/server 3.14.0 → 3.14.1

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

@@ -0,0 +1,245 @@
+/**
+ * Pins the run gate's SPLICE in agent-execution-create over the real router
+ * (P1 sp.run-gate): AuthorizeRunTarget sits after EnsureSessionOrAgentResolved
+ * and BEFORE EnsureEngineAvailable, the pre-side-effect slot and
+ * CreateDefaultInstanceIfNeeded. Pinned here: (1) each request shape is
+ * checked against its own target with its own byte-pinned copy; (2) a
+ * 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
+ * under test answers only run-gate checks (runGateOnlyAuthorizer), so every
+ * refusal here is the run gate's and nobody else's.
+ */
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+import type { Client, Transport } from "@connectrpc/connect";
+import { Code, ConnectError, createClient } from "@connectrpc/connect";
+import { createGrpcTransport } from "@connectrpc/connect-node";
+
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+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 { 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 type { AuthzDecision } from "../../../extensions/authorizer.js";
+import { runGateOnlyAuthorizer } from "../../../pipeline/__tests__/support.js";
+import {
+  ENGINE_UNAVAILABLE_MESSAGE,
+  addExecutionToSessionDeniedMessage,
+  runAgentDeniedMessage,
+  runAgentInstanceDeniedMessage,
+} from "../constants.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+const API_VERSION = "agentic.stigmer.ai/v1";
+const ORG = "acme";
+
+let dir: string;
+let server: ComposedServer;
+let decision: AuthzDecision = { kind: "allow" };
+const gate = runGateOnlyAuthorizer(() => decision);
+let agentCommand: Client<typeof AgentCommandController>;
+let command: Client<typeof AgentExecutionCommandController>;
+
+beforeAll(async () => {
+  dir = mkdtempSync(path.join(tmpdir(), "agentexecution-run-gate-test-"));
+  server = await composeServer({
+    config: loadConfig({
+      STIGMER_MODEL_REGISTRY_REFRESH: "off",
+      TEMPORAL_HOST_PORT: "127.0.0.1:1",
+      DB_PATH: path.join(dir, "stigmer.db"),
+      STORAGE_PATH: path.join(dir, "storage"),
+      ARTIFACT_LOCAL_BASE_PATH: path.join(dir, "artifacts"),
+    }),
+    logger: silentLogger,
+    portOverride: 0,
+    host: "127.0.0.1",
+    extensions: [{ name: "run-gate-test", authorizer: gate.authorizer }],
+  });
+  const port = await server.start();
+  const transport: Transport = createGrpcTransport({
+    baseUrl: `http://127.0.0.1:${port}`,
+  });
+  agentCommand = createClient(AgentCommandController, transport);
+  command = createClient(AgentExecutionCommandController, transport);
+});
+
+afterAll(async () => {
+  await server.shutdown();
+  rmSync(dir, { recursive: true, force: true });
+});
+
+async function count(kind: ApiResourceKind): Promise<number> {
+  return (await server.store.listResources(kind)).length;
+}
+
+/**
+ * An agent whose stored status names NO default instance, so a create by
+ * agent_id would have CreateDefaultInstanceIfNeeded mint one — the side
+ * effect the gate must precede.
+ */
+async function createAgentWithoutDefaultInstance(
+  name: string,
+): Promise<string> {
+  const agent = await agentCommand.create({
+    apiVersion: API_VERSION,
+    kind: "Agent",
+    metadata: { name, org: ORG },
+    spec: { instructions: "You are the agent the run-gate tests target." },
+  });
+  const id = agent.metadata!.id;
+  const stored = await server.store.getResource(
+    ApiResourceKind.agent,
+    id,
+    AgentSchema,
+  );
+  if (stored.status !== undefined) {
+    stored.status.defaultInstanceId = "";
+  }
+  await server.store.saveResource(
+    ApiResourceKind.agent,
+    id,
+    AgentSchema,
+    stored,
+  );
+  return id;
+}
+
+async function captureError(
+  run: () => Promise<unknown>,
+): Promise<ConnectError> {
+  try {
+    await run();
+  } catch (error) {
+    return ConnectError.from(error);
+  }
+  throw new Error("expected the create to reject");
+}
+
+function createInput(spec: {
+  agentId?: string;
+  sessionId?: string;
+  sessionSpec?: { agentInstanceId: string };
+}) {
+  return {
+    apiVersion: API_VERSION,
+    kind: "AgentExecution",
+    metadata: { name: "run-gate-exec", org: ORG },
+    spec: { message: "hello", ...spec },
+  };
+}
+
+describe("agent-execution-create run gate (composed server)", () => {
+  it("agent_id: denies with the agent copy, persists nothing, mints no default instance", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+    const agentId = await createAgentWithoutDefaultInstance("Private agent");
+    const executionsBefore = await count(ApiResourceKind.agent_execution);
+    const instancesBefore = await count(ApiResourceKind.agent_instance);
+
+    const err = await captureError(() =>
+      command.create(createInput({ agentId })),
+    );
+
+    expect(err.code).toBe(Code.PermissionDenied);
+    expect(err.rawMessage).toBe(runAgentDeniedMessage(agentId));
+    expect(gate.runGateChecks).toEqual([
+      {
+        permission: IamPermission.can_execute,
+        resourceKind: ApiResourceKind.agent,
+        resourceId: agentId,
+      },
+    ]);
+    expect(
+      await count(ApiResourceKind.agent_execution),
+      "no execution row",
+    ).toBe(executionsBefore);
+    expect(
+      await count(ApiResourceKind.agent_instance),
+      "no default instance minted",
+    ).toBe(instancesBefore);
+    const stored = await server.store.getResource(
+      ApiResourceKind.agent,
+      agentId,
+      AgentSchema,
+    );
+    expect(stored.status?.defaultInstanceId ?? "").toBe("");
+  });
+
+  it("session_id: denies with the session copy on session#can_create_execution_in", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+
+    const err = await captureError(() =>
+      command.create(createInput({ sessionId: "ses_01someoneelses" })),
+    );
+
+    expect(err.code).toBe(Code.PermissionDenied);
+    expect(err.rawMessage).toBe(
+      addExecutionToSessionDeniedMessage("ses_01someoneelses"),
+    );
+    expect(gate.runGateChecks).toEqual([
+      {
+        permission: IamPermission.can_create_execution_in,
+        resourceKind: ApiResourceKind.session,
+        resourceId: "ses_01someoneelses",
+      },
+    ]);
+  });
+
+  it("session_spec.agent_instance_id: denies with the instance copy", async () => {
+    decision = { kind: "deny", reason: "" };
+    gate.runGateChecks.length = 0;
+
+    const err = await captureError(() =>
+      command.create(
+        createInput({ sessionSpec: { agentInstanceId: "agi_01private" } }),
+      ),
+    );
+
+    expect(err.code).toBe(Code.PermissionDenied);
+    expect(err.rawMessage).toBe(runAgentInstanceDeniedMessage("agi_01private"));
+    expect(gate.runGateChecks[0]?.resourceKind).toBe(
+      ApiResourceKind.agent_instance,
+    );
+  });
+
+  it("not-found answers NOT_FOUND naming the target (the stigmer#224 order)", async () => {
+    decision = { kind: "not-found" };
+    const err = await captureError(() =>
+      command.create(createInput({ agentId: "agt_01missing" })),
+    );
+    expect(err.code).toBe(Code.NotFound);
+    expect(err.rawMessage).toContain("agt_01missing");
+  });
+
+  it("the gate precedes the engine gate: an ALLOWED create reaches EnsureEngineAvailable", async () => {
+    decision = { kind: "allow" };
+    gate.runGateChecks.length = 0;
+    const agentId = await createAgentWithoutDefaultInstance("Allowed agent");
+
+    const err = await captureError(() =>
+      command.create(createInput({ agentId })),
+    );
+
+    // The engineless composed server refuses at EnsureEngineAvailable —
+    // AFTER the run gate ran and allowed.
+    expect(err.code).toBe(Code.Unavailable);
+    expect(err.rawMessage).toBe(ENGINE_UNAVAILABLE_MESSAGE);
+    expect(gate.runGateChecks.map((c) => c.resourceId)).toEqual([agentId]);
+  });
+});

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

@@ -0,0 +1,117 @@
+/**
+ * Pins the agent-execution run-target resolver (P1 sp.run-gate, ruling
+ * Q-RG-2): the target is dispatched on the request shape in the CHAIN's
+ * own precedence — session_id, then session_spec.agent_instance_id, then
+ * agent_id (CreateDefaultInstanceIfNeeded / CreateSessionIfNeeded read
+ * them in exactly that order) — so the gate authorizes the target the
+ * chain will actually use. Each shape carries its own permission and its
+ * own byte-pinned deny copy; a record with none of the three has no
+ * target (EnsureSessionOrAgentResolved owns that arm as an invariant).
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+
+import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_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 {
+  addExecutionToSessionDeniedMessage,
+  runAgentDeniedMessage,
+  runAgentInstanceDeniedMessage,
+} from "../constants.js";
+import { agentExecutionRunTarget } from "../run-target.js";
+
+describe("agentExecutionRunTarget", () => {
+  it("session_id → session#can_create_execution_in", () => {
+    expect(
+      agentExecutionRunTarget(
+        create(AgentExecutionSchema, { spec: { sessionId: "ses_01abc" } }),
+      ),
+    ).toEqual({
+      permission: IamPermission.can_create_execution_in,
+      resourceKind: ApiResourceKind.session,
+      resourceId: "ses_01abc",
+      deniedMessage: addExecutionToSessionDeniedMessage("ses_01abc"),
+    });
+    expect(addExecutionToSessionDeniedMessage("ses_01abc")).toBe(
+      "unauthorized to add an execution to session 'ses_01abc'",
+    );
+  });
+
+  it("session_spec.agent_instance_id → agent_instance#can_execute", () => {
+    expect(
+      agentExecutionRunTarget(
+        create(AgentExecutionSchema, {
+          spec: { sessionSpec: { agentInstanceId: "agi_01abc" } },
+        }),
+      ),
+    ).toEqual({
+      permission: IamPermission.can_execute,
+      resourceKind: ApiResourceKind.agent_instance,
+      resourceId: "agi_01abc",
+      deniedMessage: runAgentInstanceDeniedMessage("agi_01abc"),
+    });
+    expect(runAgentInstanceDeniedMessage("agi_01abc")).toBe(
+      "unauthorized to run agent instance 'agi_01abc'",
+    );
+  });
+
+  it("agent_id → agent#can_execute", () => {
+    expect(
+      agentExecutionRunTarget(
+        create(AgentExecutionSchema, { spec: { agentId: "agt_01abc" } }),
+      ),
+    ).toEqual({
+      permission: IamPermission.can_execute,
+      resourceKind: ApiResourceKind.agent,
+      resourceId: "agt_01abc",
+      deniedMessage: runAgentDeniedMessage("agt_01abc"),
+    });
+    expect(runAgentDeniedMessage("agt_01abc")).toBe(
+      "unauthorized to run agent 'agt_01abc'",
+    );
+  });
+
+  it("precedence is the chain's: session_id wins over both, the instance over agent_id", () => {
+    const all = agentExecutionRunTarget(
+      create(AgentExecutionSchema, {
+        spec: {
+          sessionId: "ses_01abc",
+          agentId: "agt_01abc",
+          sessionSpec: { agentInstanceId: "agi_01abc" },
+        },
+      }),
+    );
+    expect(all?.resourceKind).toBe(ApiResourceKind.session);
+    expect(all?.resourceId).toBe("ses_01abc");
+
+    const instanceAndAgent = agentExecutionRunTarget(
+      create(AgentExecutionSchema, {
+        spec: {
+          agentId: "agt_01abc",
+          sessionSpec: { agentInstanceId: "agi_01abc" },
+        },
+      }),
+    );
+    expect(instanceAndAgent?.resourceKind).toBe(ApiResourceKind.agent_instance);
+    expect(instanceAndAgent?.resourceId).toBe("agi_01abc");
+  });
+
+  it("answers no target when none of the three references is set", () => {
+    expect(
+      agentExecutionRunTarget(create(AgentExecutionSchema, {})),
+    ).toBeUndefined();
+    expect(
+      agentExecutionRunTarget(
+        create(AgentExecutionSchema, {
+          spec: {
+            sessionId: "",
+            agentId: "",
+            sessionSpec: { agentInstanceId: "" },
+          },
+        }),
+      ),
+    ).toBeUndefined();
+  });
+});

package/src/domain/agentexecution/constants.ts

@@ -28,3 +28,28 @@ export function executionUsageReportNotFoundMessage(
 ): string {
   return `agent execution '%s' not found not found: ${executionId}`;
 }
+
+/**
+ * The run gate's deny copy per request shape (P1 sp.run-gate, ruling
+ * Q-RG-4; wire once merged, asserted by the conformance run-gate suite).
+ * NEW copy quotes the handle single-quoted (the ratified 2026-08-26 rule).
+ * An AgentExecution is a RUN in the ubiquitous language, hence "run";
+ * a turn added to an existing conversation is "an execution in a session",
+ * the session's own permission.
+ */
+export function runAgentDeniedMessage(agentId: string): string {
+  return `unauthorized to run agent '${agentId}'`;
+}
+
+/**
+ * Identical to the session domain's instance copy on purpose — one fact,
+ * one sentence (the ENGINE_UNAVAILABLE_MESSAGE precedent for cross-domain
+ * twins: each domain owns its constant, the twin is named here).
+ */
+export function runAgentInstanceDeniedMessage(agentInstanceId: string): string {
+  return `unauthorized to run agent instance '${agentInstanceId}'`;
+}
+
+export function addExecutionToSessionDeniedMessage(sessionId: string): string {
+  return `unauthorized to add an execution to session '${sessionId}'`;
+}

package/src/domain/agentexecution/controller.ts

@@ -44,6 +44,7 @@ import { newPipeline } from "../../pipeline/pipeline.js";
 import { callerIdentityOf } from "../../pipeline/interceptors/auth.js";
 import { RequestContext } from "../../pipeline/request-context.js";
 import { newAuthorizeStep } from "../../pipeline/steps/authorize.js";
+import { newAuthorizeRunTargetStep } from "../../pipeline/steps/authorize-run-target.js";
 import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import type { RunnerCredentialProvider } from "../../runnerauth/runner-credential-provider.js";
 import { newRecordRunnerLineageLabelsStep } from "./record-runner-lineage-labels.js";
@@ -113,6 +114,7 @@ import {
   resumeExecution,
   terminateExecution,
 } from "./lifecycle.js";
+import { agentExecutionRunTarget } from "./run-target.js";
 import { agentExecutionSearchExtractor } from "./search-extractor.js";
 import type { StreamBroker } from "./stream-broker.js";
 import { submitApproval } from "./submit-approval.js";
@@ -278,9 +280,13 @@ export function registerAgentExecutionServices(
 /**
  * Create — create.go buildCreatePipeline, step-for-step: validation
  * (proto → visibility → tier #357 → thinking #772) → target resolution
- * (default agent → invariant guard) → the standard build → the engine
- * gate (fail fast BEFORE the first side effect, so a down engine orphans
- * nothing) → the pre-side-effect gate slot (O4; empty in OSS) → the
+ * (default agent → invariant guard) → the run gate (AuthorizeRunTarget,
+ * P1 sp.run-gate: the first step after the target is guaranteed, asking
+ * the target's own permission by request shape — session, instance or
+ * blueprint — before the engine gate so a denied caller learns nothing
+ * about engine state, and before every side effect) → the standard build
+ * → the engine gate (fail fast BEFORE the first side effect, so a down
+ * engine orphans nothing) → the pre-side-effect gate slot (O4; empty in OSS) → the
  * side-effecting steps (default instance, session bootstrap,
  * preference/memory snapshots, initial phase, the ExecutionContext with
  * merged env, attachment validation) → Persist → IndexSearch →
@@ -314,6 +320,7 @@ async function createExecution(
     .addStep(newValidateThinkingModeStep(deps.modelRegistry))
     .addStep(newResolveDefaultAgentStep(deps.store, deps.logger))
     .addStep(newEnsureSessionOrAgentResolvedStep(deps.logger))
+    .addStep(newAuthorizeRunTargetStep(deps.authorizer, agentExecutionRunTarget))
     .addStep(newResolveSlugStep())
     .addStep(newBuildNewStateStep())
     // Vouches the runner-stamped workflow lineage labels (or refuses a

package/src/domain/agentexecution/run-target.ts

@@ -0,0 +1,64 @@
+/**
+ * The agent-execution run-target resolver (P1 sp.run-gate, ruling Q-RG-2):
+ * an execution names its run target in one of three shapes, and the gate
+ * dispatches on them in the CHAIN's own precedence so it authorizes the
+ * target the chain will actually use (CreateDefaultInstanceIfNeeded and
+ * CreateSessionIfNeeded read them in exactly this order):
+ *
+ *   1. spec.session_id — a turn added to an existing conversation: the
+ *      session's own permission, session#can_create_execution_in;
+ *   2. spec.session_spec.agent_instance_id — a new conversation on an
+ *      explicit instance: agent_instance#can_execute;
+ *   3. spec.agent_id — a new conversation on the blueprint's default
+ *      instance, which the chain resolves (or mints) only AFTER the gate:
+ *      agent#can_execute, the blueprint's permission (the model derives
+ *      the default instance's viewers from the blueprint's, so the two
+ *      questions have one answer; asking the blueprint's is what lets the
+ *      gate precede the side effect).
+ *
+ * None of the three set is EnsureSessionOrAgentResolved's invariant arm
+ * (ResolveDefaultAgent guarantees one), never a check. Pure over the record
+ * being built, where ResolveDefaultAgent writes the resolved agent_id.
+ */
+import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
+
+import {
+  RUN_GATE_CHECKS,
+  type RunTarget,
+} from "../../pipeline/steps/authorize-run-target.js";
+import {
+  addExecutionToSessionDeniedMessage,
+  runAgentDeniedMessage,
+  runAgentInstanceDeniedMessage,
+} from "./constants.js";
+
+export function agentExecutionRunTarget(
+  execution: AgentExecution,
+): RunTarget | undefined {
+  const spec = execution.spec;
+  const sessionId = spec?.sessionId ?? "";
+  if (sessionId !== "") {
+    return {
+      ...RUN_GATE_CHECKS.session,
+      resourceId: sessionId,
+      deniedMessage: addExecutionToSessionDeniedMessage(sessionId),
+    };
+  }
+  const agentInstanceId = spec?.sessionSpec?.agentInstanceId ?? "";
+  if (agentInstanceId !== "") {
+    return {
+      ...RUN_GATE_CHECKS.agentInstance,
+      resourceId: agentInstanceId,
+      deniedMessage: runAgentInstanceDeniedMessage(agentInstanceId),
+    };
+  }
+  const agentId = spec?.agentId ?? "";
+  if (agentId !== "") {
+    return {
+      ...RUN_GATE_CHECKS.agent,
+      resourceId: agentId,
+      deniedMessage: runAgentDeniedMessage(agentId),
+    };
+  }
+  return undefined;
+}