@stigmer/server 3.20.0 → 3.22.0

package/src/domain/agentchannel/controller.ts

@@ -66,6 +66,10 @@ import {
   authorizeDirect,
   newAuthorizeStep,
 } from "../../pipeline/steps/authorize.js";
+import {
+  loadedTargetAsMethod,
+  newAuthorizeResolvedTargetStep,
+} from "../../pipeline/steps/authorize-resolved-target.js";
 import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import { newBuildNewStateStep } from "../../pipeline/steps/defaults.js";
 import { newBuildUpdateStateStep } from "../../pipeline/steps/build-update-state.js";
@@ -110,6 +114,7 @@ import {
   newResolveChannelDefaultsStep,
   newTeardownChannelRuntimeStep,
   newValidateChannelUpdateStep,
+  resolveChannelCreateTargets,
 } from "./steps.js";
 
 export interface AgentChannelControllerDeps {
@@ -191,6 +196,14 @@ async function createChannel(
         deps.channelRuntime,
       ),
     )
+    // Before the duplicate check and the install state (steps.ts,
+    // resolveChannelCreateTargets).
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        resolveChannelCreateTargets,
+      ),
+    )
     .addStep(newResolveSlugStep())
     .addStep(newCheckDuplicateStep(deps.store))
     .addStep(newBuildNewStateStep())
@@ -499,6 +512,12 @@ async function getByReference(
     )
     .addStep(newValidateProtoStep())
     .addStep(newLoadByReferenceStep(deps.store, AgentChannelSchema))
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        loadedTargetAsMethod(AgentChannelQueryController.method.get),
+      ),
+    )
     .build()
     .execute(reqCtx);
   return reqCtx.get(TARGET_RESOURCE_KEY) as AgentChannel;

package/src/domain/agentchannel/steps.ts

@@ -21,7 +21,9 @@ import {
   AgentChannelStatusSchema,
 } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/status_pb";
 import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import type { Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/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 {
   failedPreconditionError,
@@ -31,6 +33,7 @@ import {
 } from "../../pipeline/errors.js";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
 import type { RequestContext } from "../../pipeline/request-context.js";
+import type { AuthorizationTarget } from "../../pipeline/steps/authorize.js";
 import { findResourceBySlug } from "../../pipeline/steps/helpers.js";
 import { EXISTING_RESOURCE_KEY } from "../../pipeline/steps/load-existing.js";
 import type { Store } from "../../store/interface.js";
@@ -161,6 +164,7 @@ export function newResolveChannelDefaultsStep(
       }
 
       agentRef!.org = refOrg;
+      ctx.set(REFERENCED_AGENT_KEY, agent);
 
       // Write-time constraints only a serving runtime can state (the
       // pin-REQUIRED rule and its successors — channel-runtime.ts).
@@ -174,6 +178,42 @@ export function newResolveChannelDefaultsStep(
   };
 }
 
+/**
+ * Context key for the agent ResolveChannelDefaults resolved from
+ * spec.agent_ref, read by the create lane's authorization step.
+ */
+export const REFERENCED_AGENT_KEY = "agentChannelReferencedAgent";
+
+/** The deny copy of the create bar, the Java AgentChannelCreateHandler's. */
+export const CHANNEL_CREATE_DENIED_MESSAGE =
+  "You don't have permission to connect this agent to a channel";
+
+/**
+ * The create lane's authorization question, for AuthorizeResolvedTarget
+ * after ResolveChannelDefaults: can_edit on the REFERENCED AGENT. The RPC
+ * is is_skip_authorization because its target is that agent, resolved from
+ * a slug, not a request field. Binding an agent to a channel puts it in
+ * front of a wider audience, an editor's act; the same-org invariant the
+ * resolve step enforces already binds the channel's organization to the
+ * agent's, so there is no separate organization bar (command.proto).
+ */
+export function resolveChannelCreateTargets(
+  ctx: RequestContext<AgentChannelDesc>,
+): ReadonlyArray<AuthorizationTarget> {
+  const agent = ctx.get(REFERENCED_AGENT_KEY) as Agent | undefined;
+  if (agent === undefined) {
+    throw new Error("referenced agent not found in context");
+  }
+  return [
+    {
+      permission: IamPermission.can_edit,
+      resourceKind: ApiResourceKind.agent,
+      resourceId: agent.metadata?.id ?? "",
+      deniedMessage: CHANNEL_CREATE_DENIED_MESSAGE,
+    },
+  ];
+}
+
 /**
  * InitInstallState — Go initInstallStateStep: writes
  * status.install_state = pending_install; the channel exists but serves

package/src/domain/agentexecution/__tests__/create-execution-context-step.test.ts

@@ -6,6 +6,11 @@
  * test driving a NON-EMPTY environment and a real token injection through
  * buildAndPersistExecutionContext. Go has no unit twin (its coverage is
  * the execution conformance suites); this pin is TS-only by design.
+ *
+ * Also pins the one declaration rule (the module header of the step): the
+ * agent's env united with the session servers' env, and a session
+ * server's saved key reaching the run from the personal environment — for
+ * an agent-bound run and for the built-in assistant alike.
  */
 import { mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
@@ -20,6 +25,7 @@ import { AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentins
 import { AgentExecutionSchema } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
 import type { EnvironmentValue } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import { EnvironmentValueSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
 import type { ExecutionContext } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/api_pb";
 import { McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
 import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
@@ -284,3 +290,213 @@ it("assembles merge → filter → OAuth injection → EC persist over a non-emp
   const grant = await store.oauthGrants.find("", "mcps_vendor", ORG);
   expect(grant?.accessTokenExpiresAt ?? 0).toBeGreaterThan(now);
 });
+
+// ---------------------------------------------------------------------------
+// The one declaration rule: the run declares what its agent declares AND
+// what its session's MCP servers declare, and a session server's declared
+// variables the merge chain never carried (no instance layer can) come
+// from the caller's personal environment by declared key. Two shapes, one
+// rule: an agent-bound run whose session added a server, and the built-in
+// assistant, which is the case with no agent half at all.
+// ---------------------------------------------------------------------------
+
+/** A personal environment reader over a fixed map; every read is recorded. */
+function personalEnvironmentOver(
+  org: string,
+  data: Record<string, string>,
+  reads: string[],
+): ReturnType<ExecutionContextBuilderDeps["environmentReader"]> {
+  return {
+    list: async () => ({
+      $typeName: "ai.stigmer.agentic.environment.v1.EnvironmentList",
+      totalCount: 1,
+      items: [
+        create(EnvironmentSchema, {
+          metadata: { id: "env_personal", org, slug: "personal" },
+          spec: {
+            data: Object.fromEntries(
+              Object.keys(data).map((key) => [key, { value: "***", isSecret: true }]),
+            ),
+          },
+        }),
+      ],
+    }),
+    getSecretValue: async (input) => {
+      const key = input.key ?? "";
+      reads.push(key);
+      return create(EnvironmentValueSchema, {
+        value: data[key] ?? "",
+        isSecret: true,
+      });
+    },
+  };
+}
+
+it("a session-level server's declared key saved in the personal environment reaches an agent-bound run", async () => {
+  const ORG = "acme";
+  await store.saveResource(
+    ApiResourceKind.mcp_server,
+    "mcps_github",
+    McpServerSchema,
+    create(McpServerSchema, {
+      metadata: { id: "mcps_github", org: ORG, slug: "github" },
+      spec: {
+        env: {
+          GITHUB_PAT: { isSecret: true },
+          GITHUB_ORG: { isSecret: false, optional: true },
+        },
+      },
+    }),
+  );
+  const agent = create(AgentSchema, {
+    metadata: { id: "agt_rule", org: ORG, slug: "rule-agent" },
+    // The agent declares its own key and nothing of the session's server.
+    spec: { env: { API_KEY: { isSecret: true } } },
+  });
+  const reads: string[] = [];
+  const createdEcs: ExecutionContext[] = [];
+  const deps: ExecutionContextBuilderDeps = {
+    store,
+    logger: silentLogger,
+    agentLoader: () => ({ get: async () => agent }),
+    agentInstanceLoader: () => ({
+      get: async (instanceId) =>
+        create(AgentInstanceSchema, {
+          metadata: { id: instanceId, org: ORG },
+          spec: { agentId: "agt_rule" },
+        }),
+    }),
+    sessionLoader: () => ({
+      get: async (sessionId) =>
+        create(SessionSchema, {
+          metadata: { id: sessionId, org: ORG },
+          spec: {
+            agentInstanceId: "agi_rule",
+            // Added at the session level: no instance, no environment_refs.
+            mcpServerUsages: [{ mcpServerRef: { slug: "github", org: ORG } }],
+          },
+        }),
+    }),
+    environmentReader: () =>
+      personalEnvironmentOver(ORG, { GITHUB_PAT: "ghp-saved", API_KEY: "never-read" }, reads),
+    environmentResolution: {
+      resolveByReference: async () => {
+        throw new Error("no environment refs on this instance");
+      },
+    } as unknown as ExecutionContextBuilderDeps["environmentResolution"],
+    executionContextCreator: () => ({
+      create: async (ec) => {
+        createdEcs.push(ec);
+        return ec;
+      },
+    }),
+    managedEnvService: {
+      readSecretValue: async () => "",
+      updateSecrets: async () => {},
+    } as unknown as ManagedEnvironmentService,
+  };
+  const execution = create(AgentExecutionSchema, {
+    metadata: { id: "aexec_rule", org: ORG },
+    spec: {
+      sessionId: "ses_rule",
+      message: "hi",
+      runtimeEnv: {
+        API_KEY: { value: "runtime", isSecret: true },
+        UNDECLARED: { value: "stripped", isSecret: false },
+      },
+    },
+  });
+
+  await buildAndPersistExecutionContext(deps, execution, "");
+
+  const data = createdEcs[0]?.spec?.data ?? {};
+  // The agent's own key still flows as before.
+  expect(data["API_KEY"]?.value).toBe("runtime");
+  // The session server's declared key survives the filter (the union) and
+  // is resolved from the personal environment, marked secret as declared.
+  expect(data["GITHUB_PAT"]?.value).toBe("ghp-saved");
+  expect(data["GITHUB_PAT"]?.isSecret).toBe(true);
+  // A key nobody declared is filtered, as before.
+  expect(data["UNDECLARED"]).toBeUndefined();
+  // Least privilege: only the session server's still-missing declared key
+  // the personal environment HOLDS was read — never the agent's (already
+  // present), never a key the environment lacks (the optional one is
+  // skipped on the stored-keys check, no secret read), never the whole
+  // environment.
+  expect(reads).toEqual(["GITHUB_PAT"]);
+  expect(data["GITHUB_ORG"]).toBeUndefined();
+});
+
+it("the built-in assistant: no instance, no agent, the session's servers are the declared set", async () => {
+  const ORG = "acme";
+  await store.saveResource(
+    ApiResourceKind.mcp_server,
+    "mcps_notes",
+    McpServerSchema,
+    create(McpServerSchema, {
+      metadata: { id: "mcps_notes", org: ORG, slug: "notes" },
+      spec: { env: { NOTES_TOKEN: { isSecret: true } } },
+    }),
+  );
+  const reads: string[] = [];
+  const createdEcs: ExecutionContext[] = [];
+  const deps: ExecutionContextBuilderDeps = {
+    store,
+    logger: silentLogger,
+    // Neither lane may be reached: there is no instance and no agent.
+    agentLoader: () => ({
+      get: async () => {
+        throw new Error("agent loader must not be reached");
+      },
+    }),
+    agentInstanceLoader: () => ({
+      get: async () => {
+        throw new Error("instance loader must not be reached");
+      },
+    }),
+    sessionLoader: () => ({
+      get: async (sessionId) =>
+        create(SessionSchema, {
+          metadata: { id: sessionId, org: ORG },
+          spec: {
+            agentInstanceId: "",
+            mcpServerUsages: [{ mcpServerRef: { slug: "notes", org: ORG } }],
+          },
+        }),
+    }),
+    environmentReader: () => personalEnvironmentOver(ORG, { NOTES_TOKEN: "nt-saved" }, reads),
+    environmentResolution: {
+      resolveByReference: async () => {
+        throw new Error("no environment refs without an instance");
+      },
+    } as unknown as ExecutionContextBuilderDeps["environmentResolution"],
+    executionContextCreator: () => ({
+      create: async (ec) => {
+        createdEcs.push(ec);
+        return ec;
+      },
+    }),
+    managedEnvService: {
+      readSecretValue: async () => "",
+      updateSecrets: async () => {},
+    } as unknown as ManagedEnvironmentService,
+  };
+  const execution = create(AgentExecutionSchema, {
+    metadata: { id: "aexec_assistant", org: ORG },
+    spec: {
+      sessionId: "ses_assistant",
+      message: "hi",
+      runtimeEnv: { STRAY: { value: "stripped", isSecret: false } },
+    },
+  });
+
+  await buildAndPersistExecutionContext(deps, execution, "");
+
+  expect(createdEcs).toHaveLength(1);
+  const data = createdEcs[0]?.spec?.data ?? {};
+  expect(data["NOTES_TOKEN"]?.value).toBe("nt-saved");
+  // The declared set is the session servers' alone, so the filter is
+  // live: a stray runtime key is stripped, not passed through.
+  expect(data["STRAY"]).toBeUndefined();
+  expect(reads).toEqual(["NOTES_TOKEN"]);
+});

package/src/domain/agentexecution/__tests__/create-steps.test.ts

@@ -19,7 +19,6 @@ import type { JsonObject } from "@bufbuild/protobuf";
 import { Code, ConnectError } from "@connectrpc/connect";
 import { afterEach, beforeEach, describe, expect, it } from "vitest";
 
-import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 import {
   AgentExecutionSchema,
@@ -32,6 +31,8 @@ import {
 } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/spec_pb";
 import { MemorySchema } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/api_pb";
 import { MemoryLifecycleState } from "@stigmer/protos/ai/stigmer/agentic/memory/v1/enum_pb";
+import type { Session } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
 import type { SessionSpec } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
 import { SessionSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/spec_pb";
 import {
@@ -42,7 +43,6 @@ import type { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/ap
 import { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import { WorkflowTaskKind } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/enum_pb";
 import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
-import { ApiResourceVisibility } from "@stigmer/protos/ai/stigmer/commons/apiresource/enum_pb";
 import { OrganizationSchema } from "@stigmer/protos/ai/stigmer/tenancy/organization/v1/api_pb";
 
 import { createLogger } from "../../../boot/logger.js";
@@ -59,8 +59,6 @@ import {
   newComposeRecalledMemoriesStep,
   newCreateDefaultInstanceIfNeededStep,
   newCreateSessionIfNeededStep,
-  newEnsureSessionOrAgentResolvedStep,
-  newResolveDefaultAgentStep,
   newStartWorkflowStep,
 } from "../create-steps.js";
 import type { AgentExecutionStatusTransition } from "../../../extensions/status-hooks.js";
@@ -105,28 +103,6 @@ function newContext(
   );
 }
 
-async function seedDefaultAgent(
-  id: string,
-  visibility: ApiResourceVisibility,
-): Promise<void> {
-  await store.saveResource(
-    ApiResourceKind.agent,
-    id,
-    AgentSchema,
-    create(AgentSchema, {
-      apiVersion: "agentic.stigmer.ai/v1",
-      kind: "Agent",
-      metadata: {
-        id,
-        name: "assistant",
-        org: "stigmer",
-        visibility,
-        labels: { "stigmer.ai/default-agent": "true" },
-      },
-    }),
-  );
-}
-
 async function expectCode(
   fn: () => Promise<unknown> | unknown,
   code: Code,
@@ -141,140 +117,89 @@ async function expectCode(
   throw new Error(`expected code ${Code[code]}, call succeeded`);
 }
 
-// The post-resolution invariant guard: a resolved reference passes; an
-// unresolved one is an Internal invariant violation (never
-// InvalidArgument — issue #196).
-describe("newEnsureSessionOrAgentResolvedStep", () => {
-  const step = newEnsureSessionOrAgentResolvedStep(silentLogger);
-
-  const cases: Array<{
-    name: string;
-    sessionId?: string;
-    agentId?: string;
-    specInstanceId?: string;
-    wantCode?: Code;
-  }> = [
-    { name: "session_id resolved -> pass", sessionId: "ses_1" },
-    { name: "agent_id resolved -> pass", agentId: "agt_1" },
-    {
-      name: "both resolved -> pass",
-      sessionId: "ses_1",
-      agentId: "agt_1",
-    },
-    {
-      name: "session_spec instance resolved -> pass",
-      specInstanceId: "inst_1",
-    },
-    {
-      name: "none resolved -> Internal invariant violation",
-      wantCode: Code.Internal,
-    },
-  ];
-
-  for (const tt of cases) {
-    it(tt.name, async () => {
-      const execution = newExecution(tt.sessionId ?? "", tt.agentId ?? "");
-      if (tt.specInstanceId !== undefined) {
-        execution.spec!.sessionSpec = create(SessionSpecSchema, {
-          agentInstanceId: tt.specInstanceId,
-        });
-      }
-      const ctx = newContext(execution);
-      if (tt.wantCode === undefined) {
-        await step.execute(ctx);
-      } else {
-        await expectCode(() => step.execute(ctx), tt.wantCode);
-      }
+// The built-in assistant's shape through the two side-effecting steps: an
+// execution naming no session, no agent and no session_spec instance is
+// legal (agentexecution/v1/spec.proto), so CreateDefaultInstanceIfNeeded
+// has nothing to load or mint and CreateSessionIfNeeded creates the
+// session with an EMPTY agent_instance_id. The throwing providers prove
+// the first step never reaches a client (Go's nil clients would panic).
+describe("the built-in assistant (no session, agent or instance named)", () => {
+  it("createDefaultInstanceIfNeeded skips without touching the agent lane", async () => {
+    const step = newCreateDefaultInstanceIfNeededStep({
+      store,
+      logger: silentLogger,
+      agentLoader: () => {
+        throw new Error("agent loader must not be reached");
+      },
+      agentInstanceCreator: () => {
+        throw new Error("instance creator must not be reached");
+      },
     });
-  }
-});
-
-// The reachable contract of default-agent resolution: NotFound when
-// unseeded, resolution onto newState when a public default exists, and
-// FailedPrecondition when the default is not visibility_public.
-describe("newResolveDefaultAgentStep", () => {
-  it("no default agent seeded -> NotFound", async () => {
-    const step = newResolveDefaultAgentStep(store, silentLogger);
-    await expectCode(
-      () => step.execute(newContext(newExecution("", ""))),
-      Code.NotFound,
-    );
-  });
-
-  it("public default agent -> resolves agent_id onto newState", async () => {
-    await seedDefaultAgent(
-      "agt_default",
-      ApiResourceVisibility.visibility_public,
-    );
-    const step = newResolveDefaultAgentStep(store, silentLogger);
     const ctx = newContext(newExecution("", ""));
-
     await step.execute(ctx);
-
-    expect(ctx.newState.spec?.agentId).toBe("agt_default");
-    // The original request must remain immutable.
-    expect(ctx.input.spec?.agentId).toBe("");
-  });
-
-  it("non-public default agent -> FailedPrecondition", async () => {
-    await seedDefaultAgent(
-      "agt_private",
-      ApiResourceVisibility.visibility_private,
-    );
-    const step = newResolveDefaultAgentStep(store, silentLogger);
-    await expectCode(
-      () => step.execute(newContext(newExecution("", ""))),
-      Code.FailedPrecondition,
-    );
+    expect(ctx.get(DEFAULT_INSTANCE_ID_KEY)).toBeUndefined();
   });
 
-  // The oss#356 defect through this step's lens: a first-match lookup
-  // could land on the non-public labeled agent and fail even though a
-  // valid public default existed. Both insertion orders must resolve the
-  // public agent.
-  for (const [name, ids] of Object.entries({
-    "private inserted first": ["agt_0private", "agt_1public"],
-    "public inserted first": ["agt_1public", "agt_0private"],
-  })) {
-    it(`non-public labeled agent alongside a public one -> public wins (${name})`, async () => {
-      for (const id of ids) {
-        await seedDefaultAgent(
-          id,
-          id === "agt_1public"
-            ? ApiResourceVisibility.visibility_public
-            : ApiResourceVisibility.visibility_private,
-        );
-      }
-      const step = newResolveDefaultAgentStep(store, silentLogger);
-      const ctx = newContext(newExecution("", ""));
-      await step.execute(ctx);
-      expect(ctx.newState.spec?.agentId).toBe("agt_1public");
+  it("createSessionIfNeeded creates the session with no instance and no context key", async () => {
+    let created: Session | undefined;
+    const step = newCreateSessionIfNeededStep({
+      logger: silentLogger,
+      sessionCreator: () => ({
+        createAsCaller: async (session) => {
+          created = clone(SessionSchema, session);
+          created.metadata!.id = "ses_assistant";
+          return created;
+        },
+      }),
     });
-  }
+    const execution = newExecution("", "");
+    execution.metadata!.org = "acme";
+    const ctx = newContext(execution);
 
-  it("reference already provided -> no-op", async () => {
-    const step = newResolveDefaultAgentStep(store, silentLogger);
-    const ctx = newContext(newExecution("", "agt_explicit"));
     await step.execute(ctx);
-    expect(ctx.newState.spec?.agentId).toBe("agt_explicit");
+
+    expect(created?.spec?.agentInstanceId).toBe("");
+    expect(created?.spec?.subject).toBe(AUTO_CREATED_SESSION_SUBJECT);
+    expect(created?.metadata?.org).toBe("acme");
+    expect(ctx.newState.spec?.sessionId).toBe("ses_assistant");
+    expect(ctx.newState.spec?.sessionSpec).toBeUndefined();
   });
 
-  it("session_spec instance provided -> no-op even with a seeded default agent", async () => {
-    // A one-call bootstrap naming an explicit instance must NOT resolve
-    // the platform default agent: doing so would stamp misleading
-    // metadata pointing at an agent the session does not run against.
-    await seedDefaultAgent(
-      "agt_default",
-      ApiResourceVisibility.visibility_public,
-    );
-    const step = newResolveDefaultAgentStep(store, silentLogger);
+  it("createSessionIfNeeded forwards a caller session_spec that names no instance", async () => {
+    let created: Session | undefined;
+    const step = newCreateSessionIfNeededStep({
+      logger: silentLogger,
+      sessionCreator: () => ({
+        createAsCaller: async (session) => {
+          created = clone(SessionSchema, session);
+          created.metadata!.id = "ses_assistant_tools";
+          return created;
+        },
+      }),
+    });
     const execution = newExecution("", "");
     execution.spec!.sessionSpec = create(SessionSpecSchema, {
-      agentInstanceId: "inst_explicit",
+      mcpServerUsages: [{ mcpServerRef: { org: "acme", slug: "github" } }],
     });
     const ctx = newContext(execution);
+
     await step.execute(ctx);
-    expect(ctx.newState.spec?.agentId).toBe("");
+
+    expect(created?.spec?.agentInstanceId).toBe("");
+    expect(created?.spec?.mcpServerUsages.map((u) => u.mcpServerRef?.slug)).toEqual(["github"]);
+  });
+
+  // An agent WAS named but the previous step left no key: the invariant
+  // guard stays Internal, unchanged — only the all-empty shape is legal.
+  it("createSessionIfNeeded still refuses a named agent whose instance was never resolved", async () => {
+    const step = newCreateSessionIfNeededStep({
+      logger: silentLogger,
+      sessionCreator: () => {
+        throw new Error("session creator must not be reached");
+      },
+    });
+    const ctx = newContext(newExecution("", "agt_named"));
+    await expectCode(() => step.execute(ctx), Code.Internal);
   });
 });
 

package/src/domain/agentexecution/controller.ts

@@ -94,9 +94,7 @@ import {
   newComposeRecalledMemoriesStep,
   newCreateDefaultInstanceIfNeededStep,
   newCreateSessionIfNeededStep,
-  newEnsureSessionOrAgentResolvedStep,
   newProcessAttachmentsStep,
-  newResolveDefaultAgentStep,
   newSetInitialPhaseStep,
   newStartWorkflowStep,
 } from "./create-steps.js";
@@ -280,12 +278,12 @@ export function registerAgentExecutionServices(
 
 /**
  * Create — create.go buildCreatePipeline, step-for-step: validation
- * (proto → visibility → tier #357 → thinking #772) → target resolution
- * (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
+ * (proto → visibility → tier #357 → thinking #772) → the run gate
+ * (AuthorizeRunTarget, P1 sp.run-gate: asking the target's own permission
+ * by request shape — session, instance or blueprint; the all-empty shape
+ * is the built-in assistant, admitted by Authorize's organization check
+ * and gated on nothing further — 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,
@@ -319,8 +317,6 @@ async function createExecution(
     .addStep(newValidateVisibilityStep())
     .addStep(newValidateServiceTierStep(deps.modelRegistry))
     .addStep(newValidateThinkingModeStep(deps.modelRegistry))
-    .addStep(newResolveDefaultAgentStep(deps.store, deps.logger))
-    .addStep(newEnsureSessionOrAgentResolvedStep(deps.logger))
     .addStep(
       newAuthorizeRunTargetStep(deps.authorizer, agentExecutionRunTarget),
     )