@stigmer/server 3.19.1-dev.20260920100552 → 3.21.0

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

@@ -3,6 +3,13 @@
  * compose_declared_preferences_step.go, and
  * compose_recalled_memories_step.go. The chain itself is assembled in
  * controller.ts, mirroring Go buildCreatePipeline order exactly.
+ *
+ * An execution names its target one of three ways (session_id, agent_id,
+ * session_spec.agent_instance_id) or not at all: the all-empty shape is the
+ * built-in assistant (agentexecution/v1/spec.proto), for which
+ * CreateSessionIfNeeded creates a session with no agent and the runner
+ * resolves an agent-less blueprint. Nothing here resolves a stored default
+ * agent into that shape.
  */
 import { create, fromBinary } from "@bufbuild/protobuf";
 
@@ -44,15 +51,10 @@ import {
   notFoundError,
   rethrownStatusError,
 } from "../../pipeline/errors.js";
-import { ConnectError, Code } from "@connectrpc/connect";
+import { ConnectError } from "@connectrpc/connect";
 import type { PipelineStep } from "../../pipeline/pipeline.js";
 import { ResourceNotFoundError } from "../../store/interface.js";
 import type { Store } from "../../store/interface.js";
-import {
-  DefaultAgentNotConfiguredError,
-  DefaultAgentNotPublicError,
-  findDefaultAgent,
-} from "../agent/defaultagent.js";
 import { buildDefaultInstanceRequest } from "../agentinstance/defaultinstance.js";
 
 import type { AgentExecutionStatusObserver } from "../../extensions/status-hooks.js";
@@ -94,120 +96,6 @@ export interface SessionCreator {
 }
 export type SessionCreatorProvider = () => SessionCreator;
 
-// ---------------------------------------------------------------------------
-// ResolveDefaultAgent — create.go resolveDefaultAgentStep.
-// ---------------------------------------------------------------------------
-
-/**
- * Resolves the platform's public default agent when neither session_id
- * nor agent_id (nor a session_spec instance) is provided — the
- * session-first UX, a VALID request shape, not an input error. Resolution
- * (candidate set, visibility preference, deterministic incumbent-wins
- * tie-break) is owned by the defaultagent module, shared with the
- * Agent.GetDefault RPC and session create.
- */
-export function newResolveDefaultAgentStep(
-  store: Store,
-  logger: Logger,
-): PipelineStep<CreateDesc> {
-  return {
-    name: "ResolveDefaultAgent",
-    async execute(ctx) {
-      const spec = ctx.input.spec;
-      if (
-        (spec?.sessionId ?? "") !== "" ||
-        (spec?.agentId ?? "") !== "" ||
-        (spec?.sessionSpec?.agentInstanceId ?? "") !== ""
-      ) {
-        return;
-      }
-
-      logger.info(
-        "Neither session_id nor agent_id provided, resolving platform default agent",
-      );
-
-      let defaultAgent: Agent;
-      try {
-        defaultAgent = await findDefaultAgent(store, logger);
-      } catch (error) {
-        if (error instanceof DefaultAgentNotConfiguredError) {
-          // Caller-actionable message: the create caller can fix this by
-          // supplying a reference — deliberately different from the
-          // Agent.GetDefault RPC's message, whose caller cannot.
-          throw new ConnectError(
-            "No default agent is configured on this platform. Provide session_id or agent_id explicitly, or seed an agent labeled stigmer.ai/default-agent=true with visibility_public",
-            Code.NotFound,
-          );
-        }
-        if (error instanceof DefaultAgentNotPublicError) {
-          throw failedPreconditionError(
-            "Default agent exists but is not visibility_public",
-          );
-        }
-        // Store/decode failure — an internal fault, not "no default
-        // agent". The sanitized wire copy keeps the cause off the wire
-        // (stigmer/stigmer#478).
-        throw internalError(
-          error,
-          "failed to resolve the platform default agent",
-        );
-      }
-
-      const resolvedId = defaultAgent.metadata?.id ?? "";
-      logger.info("Resolved platform default agent", {
-        agentId: resolvedId,
-        agentName: defaultAgent.metadata?.name ?? "",
-      });
-
-      // Set agent_id on newState (not input): later steps and Persist
-      // operate on newState.
-      const newState = ctx.newState;
-      const newSpec = (newState.spec ??= create(AgentExecutionSpecSchema));
-      newSpec.agentId = resolvedId;
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// EnsureSessionOrAgentResolved — the invariant guard.
-// ---------------------------------------------------------------------------
-
-/**
- * Asserts the post-condition that a session, agent, or
- * embedded-session-spec instance reference has been resolved. An
- * invariant guard, NOT input validation: ResolveDefaultAgent runs first
- * and guarantees one of the three or an error, so reaching this step with
- * none set is a server-side programming error — hence Internal, not
- * InvalidArgument. Deliberately diverges from WorkflowExecution's
- * validateWorkflowOrInstanceStep (InvalidArgument), whose check is
- * genuinely reachable (issue #196) — do not "harmonize" the two.
- */
-export function newEnsureSessionOrAgentResolvedStep(
-  logger: Logger,
-): PipelineStep<CreateDesc> {
-  return {
-    name: "EnsureSessionOrAgentResolved",
-    execute(ctx) {
-      const spec = ctx.newState.spec;
-      const hasSessionId = (spec?.sessionId ?? "") !== "";
-      const hasAgentId = (spec?.agentId ?? "") !== "";
-      const hasSpecInstanceId =
-        (spec?.sessionSpec?.agentInstanceId ?? "") !== "";
-      if (!hasSessionId && !hasAgentId && !hasSpecInstanceId) {
-        logger.error(
-          "Invariant violated: no session, agent, or session_spec instance reference resolved after ResolveDefaultAgent",
-        );
-        throw internalError(
-          new Error(
-            "neither session_id, agent_id, nor session_spec.agent_instance_id set after ResolveDefaultAgent",
-          ),
-          "execution target not resolved",
-        );
-      }
-    },
-  };
-}
-
 // ---------------------------------------------------------------------------
 // EnsureEngineAvailable lives in engine.ts (Phase 1); re-exported by the
 // controller for chain assembly.
@@ -233,11 +121,13 @@ export type ExecutionAgentInstanceCreatorProvider =
 
 /**
  * Ensures the referenced agent has a default instance: skips when a
- * session or explicit session_spec instance names the target; loads the
- * agent via the in-process client, creates the default instance when the
- * status lacks one, saves the agent status DIRECTLY to the store
- * (matching Go/Java: repo save, not the Update pipeline), and stores the
- * instance id in the context for the next step.
+ * session or explicit session_spec instance names the target, and when no
+ * agent is named at all (the built-in assistant: there is no agent whose
+ * instance could be created); otherwise loads the agent via the in-process
+ * client, creates the default instance when the status lacks one, saves
+ * the agent status DIRECTLY to the store (matching Go/Java: repo save, not
+ * the Update pipeline), and stores the instance id in the context for the
+ * next step.
  */
 export function newCreateDefaultInstanceIfNeededStep(deps: {
   store: Store;
@@ -261,8 +151,7 @@ export function newCreateDefaultInstanceIfNeededStep(deps: {
         return;
       }
       // An explicit session_spec instance fully specifies the target — no
-      // agent load or default-instance creation needed (a default-agent
-      // lookup would stamp misleading metadata).
+      // agent load or default-instance creation needed.
       const specInstanceId = execution.spec?.sessionSpec?.agentInstanceId ?? "";
       if (specInstanceId !== "") {
         deps.logger.debug(
@@ -271,6 +160,14 @@ export function newCreateDefaultInstanceIfNeededStep(deps: {
         );
         return;
       }
+      // No agent named: the built-in assistant runs in a session with no
+      // instance, so there is nothing to load or create here.
+      if (agentId === "") {
+        deps.logger.debug(
+          "No agent named, the built-in assistant runs; skipping default instance check",
+        );
+        return;
+      }
 
       // 1. Load agent via in-process gRPC (single source of truth). Go
       // returns the client error AS-IS here (create.go: "already a gRPC
@@ -385,7 +282,9 @@ export function newCreateDefaultInstanceIfNeededStep(deps: {
  * bootstrap, stigmer/stigmer#249) is CLONED and forwarded so the session
  * carries workspace_entries, harness, execution_target, MCP servers, and
  * skills from a single create call; defaults fill in the instance (when
- * the spec names none) and the subject sentinel (when empty).
+ * the spec names none and an agent's default instance was resolved; an
+ * empty id here and there is the built-in assistant) and the subject
+ * sentinel (when empty).
  */
 export function buildAutoCreateSessionSpec(
   callerSpec: SessionSpec | undefined,
@@ -407,11 +306,12 @@ export function buildAutoCreateSessionSpec(
 /**
  * Auto-creates the session when session_id is absent: forwards the
  * caller's session_spec, fills the instance from the previous step's
- * context key when needed, owns the session under the CALLER's org (never
- * the agent's — cross-org public agents stay usable), updates the
- * execution with the created id, and CLEARS session_spec (the Session
- * resource is the single source of truth; the persisted execution never
- * carries a second copy that could drift).
+ * context key when an agent was named, leaves it empty for the built-in
+ * assistant, owns the session under the CALLER's org (never the agent's —
+ * cross-org agents stay usable), updates the execution with the created
+ * id, and CLEARS session_spec (the Session resource is the single source
+ * of truth; the persisted execution never carries a second copy that
+ * could drift).
  */
 export function newCreateSessionIfNeededStep(deps: {
   logger: Logger;
@@ -440,12 +340,12 @@ export function newCreateSessionIfNeededStep(deps: {
         hasSessionSpec: callerSpec !== undefined,
       });
 
-      // 1. Resolve the instance when the caller's spec does not name one.
-      // The previous step resolved it and only skips when the spec
-      // carries an explicit instance, so the key is present exactly when
-      // needed.
+      // 1. Resolve the instance when the caller's spec does not name one
+      // and an agent was named: the previous step put the agent's default
+      // instance under the context key exactly then. With no agent the
+      // session is created with no instance — the built-in assistant.
       let defaultInstanceId = "";
-      if ((callerSpec?.agentInstanceId ?? "") === "") {
+      if ((callerSpec?.agentInstanceId ?? "") === "" && agentId !== "") {
         const resolved = ctx.get(DEFAULT_INSTANCE_ID_KEY);
         if (typeof resolved !== "string" || resolved === "") {
           deps.logger.error("DEFAULT_INSTANCE_ID not found in context", {

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

@@ -16,9 +16,13 @@
  *      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.
+ * None of the three set is the built-in assistant
+ * (agentexecution/v1/spec.proto): a new conversation with no agent, for
+ * which there is no blueprint to spend and so no target to check. The
+ * Authorize step ahead of the gate admitted it with the organization's
+ * can_create_execution_in; CreateSessionIfNeeded then creates the session
+ * with no instance, and every later turn arrives in shape 1. Pure over the
+ * record being built.
  */
 import type { AgentExecution } from "@stigmer/protos/ai/stigmer/agentic/agentexecution/v1/api_pb";
 

package/src/domain/environment/__tests__/personal.test.ts

@@ -0,0 +1,143 @@
+/**
+ * Pins the shared personal-environment lookup (personal.ts) on the seam
+ * both its callers stand on: outcomes are VALUES (no personal environment;
+ * resolved with the required keys still missing named), a declaration's
+ * is_secret rides onto the value, optional keys are skipped silently in
+ * every absent arm, only stored keys are read (existence before the
+ * secret read; own-key membership), and a failing list is the one thrown
+ * fault. The connect lane's refusals over these outcomes are pinned in
+ * mcpserver/__tests__/connect.test.ts; the build's warnings in
+ * agentexecution/__tests__/create-execution-context-step.test.ts.
+ */
+import { create } from "@bufbuild/protobuf";
+import { Code, ConnectError } from "@connectrpc/connect";
+import { describe, expect, it } from "vitest";
+
+import { EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentListSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/io_pb";
+import {
+  EnvVarDeclarationSchema,
+  EnvironmentValueSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+
+import { createLogger } from "../../../boot/logger.js";
+import { PERSONAL_LABEL_KEY, PERSONAL_LABEL_VALUE } from "../constants.js";
+import type { PersonalEnvironmentReader } from "../personal.js";
+import { resolveDeclaredFromPersonalEnvironment } from "../personal.js";
+
+const silentLogger = createLogger({
+  level: "error",
+  pretty: false,
+  write: () => {},
+});
+
+/** A declaration literal as the generated message. */
+function decl(init: { isSecret: boolean; optional?: boolean }) {
+  return create(EnvVarDeclarationSchema, init);
+}
+
+function readerOver(
+  stored: Record<string, string>,
+  reads: string[],
+  failing: ReadonlySet<string> = new Set(),
+): PersonalEnvironmentReader {
+  return {
+    list: async (request) => {
+      expect(request.labels).toEqual({ [PERSONAL_LABEL_KEY]: PERSONAL_LABEL_VALUE });
+      return create(EnvironmentListSchema, {
+        totalCount: 1,
+        items: [
+          create(EnvironmentSchema, {
+            metadata: { id: "env_p", org: "acme", slug: "personal" },
+            spec: {
+              data: Object.fromEntries(
+                Object.keys(stored).map((k) => [k, { value: "***", isSecret: true }]),
+              ),
+            },
+          }),
+        ],
+      });
+    },
+    getSecretValue: async (input) => {
+      const key = input.key ?? "";
+      reads.push(key);
+      if (failing.has(key)) {
+        throw new ConnectError("decrypt failed", Code.Internal);
+      }
+      return create(EnvironmentValueSchema, { value: stored[key] ?? "", isSecret: true });
+    },
+  };
+}
+
+describe("resolveDeclaredFromPersonalEnvironment", () => {
+  it("answers no-personal-environment as a value when the org has none", async () => {
+    const reader: PersonalEnvironmentReader = {
+      list: async () => create(EnvironmentListSchema, { totalCount: 0, items: [] }),
+      getSecretValue: async () => {
+        throw new Error("unreached");
+      },
+    };
+    const out = await resolveDeclaredFromPersonalEnvironment(reader, silentLogger, "acme", {
+      TOKEN: decl({ isSecret: true }),
+    });
+    expect(out).toEqual({ kind: "no-personal-environment" });
+  });
+
+  it("resolves stored keys with the declaration's is_secret, names missing required keys, skips optional ones", async () => {
+    const reads: string[] = [];
+    const reader = readerOver({ TOKEN: "t-1", PUBLIC_URL: "https://x", EMPTY: "" }, reads);
+    const out = await resolveDeclaredFromPersonalEnvironment(reader, silentLogger, "acme", {
+      TOKEN: decl({ isSecret: true }),
+      PUBLIC_URL: decl({ isSecret: false }),
+      EMPTY: decl({ isSecret: true }),
+      ABSENT_REQUIRED: decl({ isSecret: true }),
+      ABSENT_OPTIONAL: decl({ isSecret: true, optional: true }),
+    });
+    expect(out.kind).toBe("resolved");
+    if (out.kind !== "resolved") return;
+    expect(out.values["TOKEN"]?.value).toBe("t-1");
+    expect(out.values["TOKEN"]?.isSecret).toBe(true);
+    expect(out.values["PUBLIC_URL"]?.value).toBe("https://x");
+    expect(out.values["PUBLIC_URL"]?.isSecret).toBe(false);
+    // An empty stored value is absent; required → missing.
+    expect(out.values["EMPTY"]).toBeUndefined();
+    expect([...out.missing].sort()).toEqual(["ABSENT_REQUIRED", "EMPTY"]);
+    // Only stored keys are read: absent declarations cost no secret read.
+    expect(reads.sort()).toEqual(["EMPTY", "PUBLIC_URL", "TOKEN"]);
+  });
+
+  it("treats a failing secret read as absent: missing when required, skipped when optional", async () => {
+    const reads: string[] = [];
+    const reader = readerOver({ A: "a", B: "b" }, reads, new Set(["A", "B"]));
+    const out = await resolveDeclaredFromPersonalEnvironment(reader, silentLogger, "acme", {
+      A: decl({ isSecret: true }),
+      B: decl({ isSecret: true, optional: true }),
+    });
+    expect(out).toEqual({ kind: "resolved", values: {}, missing: ["A"] });
+  });
+
+  it("never reads a prototype name as a stored key", async () => {
+    const reads: string[] = [];
+    const reader = readerOver({}, reads);
+    const out = await resolveDeclaredFromPersonalEnvironment(reader, silentLogger, "acme", {
+      constructor: decl({ isSecret: true }),
+      toString: decl({ isSecret: true, optional: true }),
+    });
+    expect(out).toEqual({ kind: "resolved", values: {}, missing: ["constructor"] });
+    expect(reads).toEqual([]);
+  });
+
+  it("throws Internal when the personal environment cannot be listed", async () => {
+    const reader: PersonalEnvironmentReader = {
+      list: async () => {
+        throw new Error("store offline");
+      },
+      getSecretValue: async () => {
+        throw new Error("unreached");
+      },
+    };
+    await expect(
+      resolveDeclaredFromPersonalEnvironment(reader, silentLogger, "acme", { A: decl({ isSecret: true }) }),
+    ).rejects.toMatchObject({ code: Code.Internal });
+  });
+});

package/src/domain/environment/personal.ts

@@ -0,0 +1,141 @@
+/**
+ * The caller's personal environment as a source of DECLARED variables: the
+ * one lookup that answers "which of these declared keys does the person
+ * have saved" for every lane that runs a tool on the person's behalf.
+ *
+ * Two lanes need it and must agree on it. The MCP connect lane (the
+ * discovery run a person triggers from the console) resolves a server's
+ * declared variables here when no one-time runtime_env was supplied; the
+ * agent-execution ExecutionContext build resolves a SESSION-level MCP
+ * server's declared variables here when the merge chain did not carry them,
+ * because a session's own servers ride no agent instance and so have no
+ * environment_refs of their own. Before the build learned this rule a key
+ * saved through the console's "save for future" reached the connect lane
+ * and never the run.
+ *
+ * Least privilege by construction: only the keys the caller declares are
+ * read, one GetSecretValue per key; nothing here layers a whole
+ * environment onto anything. What a missing personal environment or a
+ * missing required key MEANS is the caller's to decide — connect refuses
+ * (a person asked to connect and cannot without the credential), the
+ * build warns (the run fails at the tool with a clearer error) — so both
+ * outcomes are returned as values, never thrown. A failing list read is
+ * the one infrastructure fault, thrown as Internal.
+ *
+ * Proven by __tests__/personal.test.ts; the connect lane's wire copy over
+ * these outcomes by mcpserver/__tests__/connect.test.ts.
+ */
+import { create } from "@bufbuild/protobuf";
+import type { MessageInitShape } from "@bufbuild/protobuf";
+
+import type { EnvironmentList } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/io_pb";
+import type {
+  EnvironmentSecretValueInputSchema,
+  ListEnvironmentsRequestSchema,
+} from "@stigmer/protos/ai/stigmer/agentic/environment/v1/io_pb";
+import type {
+  EnvVarDeclaration,
+  EnvironmentValue,
+} from "@stigmer/protos/ai/stigmer/agentic/environment/v1/spec_pb";
+import type { ExecutionValue } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+import { ExecutionValueSchema } from "@stigmer/protos/ai/stigmer/agentic/executioncontext/v1/spec_pb";
+
+import type { Logger } from "../../boot/logger.js";
+import { internalError } from "../../pipeline/errors.js";
+import { PERSONAL_LABEL_KEY, PERSONAL_LABEL_VALUE } from "./constants.js";
+
+/**
+ * The narrow environment read surface this lookup consumes: the list RPC
+ * (to find the personal environment by its label) and the secret read
+ * (decrypted; the ordinary Environment surface redacts, oss#405). Both
+ * consuming domains' in-process edges already satisfy it.
+ */
+export interface PersonalEnvironmentReader {
+  list(
+    request: MessageInitShape<typeof ListEnvironmentsRequestSchema>,
+  ): Promise<EnvironmentList>;
+  getSecretValue(
+    input: MessageInitShape<typeof EnvironmentSecretValueInputSchema>,
+  ): Promise<EnvironmentValue>;
+}
+
+/** What the lookup found; the caller decides what each outcome means. */
+export type PersonalEnvironmentResolution =
+  | { readonly kind: "no-personal-environment" }
+  | {
+      readonly kind: "resolved";
+      /** The declared keys the personal environment held, as execution values. */
+      readonly values: { readonly [key: string]: ExecutionValue };
+      /**
+       * The REQUIRED declared keys the personal environment did not hold
+       * (absent, unreadable, or empty). Optional keys never appear here.
+       */
+      readonly missing: readonly string[];
+    };
+
+/**
+ * Resolves the given declarations against the caller's personal
+ * environment in `org`. A declaration's `is_secret` rides onto the value;
+ * a declared key the environment lacks is skipped when optional and
+ * reported in `missing` when required. A secret read that fails is logged
+ * and treated as absent, the same way for both lanes.
+ */
+export async function resolveDeclaredFromPersonalEnvironment(
+  reader: PersonalEnvironmentReader,
+  logger: Logger,
+  org: string,
+  declarations: { readonly [key: string]: EnvVarDeclaration },
+): Promise<PersonalEnvironmentResolution> {
+  let listResponse: EnvironmentList;
+  try {
+    listResponse = await reader.list({
+      org,
+      labels: { [PERSONAL_LABEL_KEY]: PERSONAL_LABEL_VALUE },
+    });
+  } catch (error) {
+    throw internalError(error, "failed to list personal environments");
+  }
+  if (listResponse.totalCount === 0 || listResponse.items.length === 0) {
+    return { kind: "no-personal-environment" };
+  }
+
+  const personalEnv = listResponse.items[0];
+  const personalEnvId = personalEnv?.metadata?.id ?? "";
+  // The stored keys are present even when their values are redacted, so
+  // existence is checkable before the secret read. Own-key membership
+  // (never the prototype chain): an exotic key name must not read as held.
+  const stored = personalEnv?.spec?.data ?? {};
+
+  const values: { [key: string]: ExecutionValue } = {};
+  const missing: string[] = [];
+  for (const [key, decl] of Object.entries(declarations)) {
+    if (!Object.hasOwn(stored, key)) {
+      if (!decl.optional) missing.push(key);
+      continue;
+    }
+    let secretValue: EnvironmentValue;
+    try {
+      secretValue = await reader.getSecretValue({
+        environmentId: personalEnvId,
+        key,
+      });
+    } catch (error) {
+      logger.warn("Failed to get secret value from personal environment", {
+        key,
+        personal_env_id: personalEnvId,
+        error: error instanceof Error ? error.message : String(error),
+      });
+      if (!decl.optional) missing.push(key);
+      continue;
+    }
+    if (secretValue.value === "") {
+      if (!decl.optional) missing.push(key);
+      continue;
+    }
+    values[key] = create(ExecutionValueSchema, {
+      value: secretValue.value,
+      isSecret: decl.isSecret,
+    });
+  }
+  return { kind: "resolved", values, missing };
+}