@stigmer/server 3.23.1-dev.20260923075205 → 3.25.0

package/src/domain/workflow/__tests__/agent-call-references.test.ts

@@ -1,40 +1,50 @@
 /**
  * Pins the workflow domain's collector for the reference rule
- * (../agent-call-references.ts): the strict `slug` / `org/slug` parser and
- * its refusal copy, the walk over top-level, nested and compensate tasks
- * in declaration order with the bare form resolved to the workflow's
- * organization, a config that does not decode skipped rather than
- * double-reported, and the step over a real store answering the rule's
- * verdicts — a missing agent with the rule's copy, another organization's
- * org-visible agent with the one cross-organization sentence, a
- * platform-visible one admitted.
+ * (../agent-call-references.ts): the classifier's four forms (a literal
+ * `org/slug`, a relative bare slug, a value holding `${` that is fixed
+ * only at run, anything else malformed) and the refusal copy; the walk
+ * over top-level, nested and compensate tasks in declaration order, the
+ * relative form filled with the workflow's organization and marked, a
+ * run-time value collected as nothing; a config that does not decode
+ * skipped rather than double-reported; the step over a real store
+ * answering the rule's verdicts — a missing agent with the rule's copy,
+ * another organization's org-visible agent with the one
+ * cross-organization sentence, a platform-visible one admitted, the floor
+ * for a literal, the floor capped at org for a bare slug, a run-time value
+ * saved with no agent behind it; and the workflow's escalation door
+ * applying the same cap when a workflow calling a bare slug is raised to
+ * platform.
  */
 import { create } 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 { Workflow } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 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 type { WorkflowSpec } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_pb";
 import { WorkflowSpecSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/spec_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 { UpdateVisibilityInputSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
 
 import { RequestContext } from "../../../pipeline/request-context.js";
 import { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
 import {
+  belowFloorMessage,
   missingReferencesMessage,
+  newGuardReferenceFloorOnEscalationStep,
   notAvailableReferenceMessage,
   referenceTargetKind,
 } from "../../../pipeline/steps/references.js";
 import type { SqliteStore } from "../../../store/sqlite/store.js";
 import { tempStore } from "../../../store/sqlite/__tests__/support.js";
 import {
+  classifyAgentReference,
   collectAgentCallReferences,
   malformedAgentReferenceMessage,
   newValidateAgentCallReferencesStep,
-  parseAgentReference,
 } from "../agent-call-references.js";
 
 const V = ApiResourceVisibility;
@@ -52,24 +62,48 @@ function specOf(tasks: ReadonlyArray<Record<string, unknown>>): WorkflowSpec {
   return create(WorkflowSpecSchema, { tasks } as never);
 }
 
-describe("parseAgentReference", () => {
-  it("accepts `slug` and `org/slug` and nothing else", () => {
-    expect(parseAgentReference("reviewer")).toEqual({
-      org: "",
+/** The three shapes the runner evaluates, whole and embedded, as authors write them. */
+const RUN_TIME_VALUES = [
+  "${.env_vars.TEAM_ORG}/assistant",
+  "${.secrets.AGENT_REF}",
+  '${ "acme/reviewer" }',
+  "${ .input.agent }",
+  "acme/${ .input.slug }",
+  "${ .input.org }/a/b",
+];
+
+describe("classifyAgentReference", () => {
+  it("reads `org/slug` as a literal and a bare slug as relative", () => {
+    expect(classifyAgentReference("acme/reviewer")).toEqual({
+      kind: "literal",
+      org: "acme",
       slug: "reviewer",
     });
-    expect(parseAgentReference("acme/reviewer")).toEqual({
-      org: "acme",
+    expect(classifyAgentReference("reviewer")).toEqual({
+      kind: "relative",
       slug: "reviewer",
     });
+  });
+
+  it("reads any value holding `${` as fixed only at run, whatever its shape", () => {
+    for (const value of RUN_TIME_VALUES) {
+      expect(classifyAgentReference(value), value).toEqual({
+        kind: "run-time",
+      });
+    }
+  });
+
+  it("reads everything else as malformed", () => {
     for (const malformed of ["", "/reviewer", "acme/", "a/b/c", "//"]) {
-      expect(parseAgentReference(malformed), malformed).toBeUndefined();
+      expect(classifyAgentReference(malformed), malformed).toEqual({
+        kind: "malformed",
+      });
     }
   });
 });
 
 describe("collectAgentCallReferences", () => {
-  it("collects top-level, nested and compensate agent_call tasks in declaration order, the bare form resolved to the workflow's organization", () => {
+  it("collects top-level, nested and compensate agent_call tasks in declaration order, a bare slug filled with the workflow's organization and marked relative", () => {
     const spec = specOf([
       agentCall("first", "reviewer"),
       {
@@ -96,9 +130,29 @@ describe("collectAgentCallReferences", () => {
       },
     ]);
     expect(collectAgentCallReferences(spec, "acme")).toEqual([
-      { kind: ApiResourceKind.agent, org: "acme", slug: "reviewer" },
+      {
+        kind: ApiResourceKind.agent,
+        org: "acme",
+        slug: "reviewer",
+        resolvesIn: "running-organization",
+      },
+      { kind: ApiResourceKind.agent, org: "globex", slug: "summarizer" },
+      {
+        kind: ApiResourceKind.agent,
+        org: "acme",
+        slug: "cleaner",
+        resolvesIn: "running-organization",
+      },
+    ]);
+  });
+
+  it("collects nothing for a value fixed only at run, beside the references it does collect", () => {
+    const spec = specOf([
+      ...RUN_TIME_VALUES.map((value, i) => agentCall(`dynamic_${i}`, value)),
+      agentCall("fixed", "globex/summarizer"),
+    ]);
+    expect(collectAgentCallReferences(spec, "acme")).toEqual([
       { kind: ApiResourceKind.agent, org: "globex", slug: "summarizer" },
-      { kind: ApiResourceKind.agent, org: "acme", slug: "cleaner" },
     ]);
   });
 
@@ -162,16 +216,19 @@ describe("ValidateAgentCallReferences over a store", () => {
     );
   }
 
-  function workflowCalling(...agents: string[]) {
+  function workflowCalling(
+    visibility: ApiResourceVisibility,
+    ...agents: string[]
+  ): Workflow {
     return create(WorkflowSchema, {
       apiVersion: "agentic.stigmer.ai/v1",
       kind: "Workflow",
-      metadata: { name: "Pipeline", org: "acme", visibility: V.visibility_org },
+      metadata: { id: "wfl_1", name: "Pipeline", org: "acme", visibility },
       spec: specOf(agents.map((agent, i) => agentCall(`call_${i}`, agent))),
     });
   }
 
-  async function run(workflow: ReturnType<typeof workflowCalling>) {
+  async function run(workflow: Workflow): Promise<unknown> {
     const ctx = new RequestContext(
       WorkflowSchema,
       workflow,
@@ -187,21 +244,27 @@ describe("ValidateAgentCallReferences over a store", () => {
   }
 
   it("a missing agent is refused with the rule's copy; an existing one passes", async () => {
-    const error = await run(workflowCalling("reviewer"));
+    const error = await run(workflowCalling(V.visibility_org, "reviewer"));
     expect(error).toBeInstanceOf(ConnectError);
     expect((error as ConnectError).code).toBe(Code.FailedPrecondition);
     expect((error as ConnectError).rawMessage).toBe(
       missingReferencesMessage(AGENT, [{ slug: "reviewer", org: "acme" }]),
     );
     await seedAgent("agt_1", "acme", "reviewer", V.visibility_org);
-    expect(await run(workflowCalling("reviewer"))).toBeUndefined();
+    expect(
+      await run(workflowCalling(V.visibility_org, "reviewer")),
+    ).toBeUndefined();
   });
 
   it("another organization's agent is admitted only at platform visibility, with the one sentence otherwise", async () => {
     await seedAgent("agt_shared", "globex", "shared", V.visibility_platform);
     await seedAgent("agt_internal", "globex", "internal", V.visibility_org);
-    expect(await run(workflowCalling("globex/shared"))).toBeUndefined();
-    const error = await run(workflowCalling("globex/internal"));
+    expect(
+      await run(workflowCalling(V.visibility_org, "globex/shared")),
+    ).toBeUndefined();
+    const error = await run(
+      workflowCalling(V.visibility_org, "globex/internal"),
+    );
     expect((error as ConnectError).rawMessage).toBe(
       notAvailableReferenceMessage(AGENT, {
         kind: ApiResourceKind.agent,
@@ -213,10 +276,98 @@ describe("ValidateAgentCallReferences over a store", () => {
 
   it("the floor holds for the agent a workflow calls: an org-visible workflow may not call a private agent", async () => {
     await seedAgent("agt_mine", "acme", "mine", V.visibility_private);
-    const error = await run(workflowCalling("mine"));
+    const error = await run(workflowCalling(V.visibility_org, "mine"));
     expect((error as ConnectError).code).toBe(Code.FailedPrecondition);
     expect((error as ConnectError).rawMessage).toContain(
       "referenced agent 'acme/mine' is visibility_private while this resource is visibility_org",
     );
   });
+
+  it("a platform-visible workflow may call its organization's org-visible agent by bare slug, never by literal, and never a private one", async () => {
+    await seedAgent("agt_team", "acme", "team", V.visibility_org);
+    await seedAgent("agt_mine", "acme", "mine", V.visibility_private);
+    expect(
+      await run(workflowCalling(V.visibility_platform, "team")),
+    ).toBeUndefined();
+    // The literal names a fixed row that every organization's runs read.
+    const literal = await run(
+      workflowCalling(V.visibility_platform, "acme/team"),
+    );
+    expect((literal as ConnectError).rawMessage).toContain(
+      "referenced agent 'acme/team' is visibility_org while this resource is visibility_platform",
+    );
+    const below = await run(workflowCalling(V.visibility_platform, "mine"));
+    expect((below as ConnectError).rawMessage).toContain(
+      "referenced agent 'acme/mine' is visibility_private while this resource is visibility_platform",
+    );
+  });
+
+  it("a value fixed only at run saves with no agent behind it, at every level", async () => {
+    for (const visibility of [
+      V.visibility_private,
+      V.visibility_org,
+      V.visibility_platform,
+    ]) {
+      expect(
+        await run(workflowCalling(visibility, ...RUN_TIME_VALUES)),
+        V[visibility],
+      ).toBeUndefined();
+    }
+  });
+
+  describe("the workflow's escalation door", () => {
+    const TARGET = "loadedWorkflow";
+
+    async function escalate(
+      stored: Workflow,
+      requested: ApiResourceVisibility,
+    ): Promise<unknown> {
+      const ctx = new RequestContext(
+        UpdateVisibilityInputSchema,
+        create(UpdateVisibilityInputSchema, {
+          resourceId: "wfl_1",
+          visibility: requested,
+        }),
+        testCallerIdentity(),
+        ApiResourceKind.workflow,
+      );
+      ctx.set(TARGET, stored);
+      try {
+        await newGuardReferenceFloorOnEscalationStep(store, TARGET, [
+          (row) =>
+            collectAgentCallReferences(
+              (row as Workflow).spec,
+              (row as Workflow).metadata?.org ?? "",
+            ),
+        ]).execute(ctx);
+        return undefined;
+      } catch (error) {
+        return error;
+      }
+    }
+
+    it("raising a workflow that calls a bare slug to platform asks the capped floor", async () => {
+      await seedAgent("agt_team", "acme", "team", V.visibility_org);
+      await seedAgent("agt_mine", "acme", "mine", V.visibility_private);
+      expect(
+        await escalate(
+          workflowCalling(V.visibility_org, "team"),
+          V.visibility_platform,
+        ),
+      ).toBeUndefined();
+      const error = await escalate(
+        workflowCalling(V.visibility_private, "mine"),
+        V.visibility_platform,
+      );
+      expect((error as ConnectError).code).toBe(Code.FailedPrecondition);
+      expect((error as ConnectError).rawMessage).toBe(
+        belowFloorMessage(
+          AGENT,
+          { kind: ApiResourceKind.agent, org: "acme", slug: "mine" },
+          V.visibility_private,
+          V.visibility_platform,
+        ),
+      );
+    });
+  });
 });

package/src/domain/workflow/agent-call-references.ts

@@ -1,31 +1,50 @@
 /**
  * ValidateAgentCallReferences — the second collector for the reference rule
  * (pipeline/steps/references.ts): a workflow's `agent_call` tasks name their
- * agent as a STRING, `"slug"` or `"org/slug"`, inside a `google.protobuf.Struct`
- * config the generic spec walker cannot see, so the rule would never meet
- * them. This step parses each task's config through the converter's own
- * strict decoder (`unmarshalTaskConfig`, the one reader of a task config),
- * walks nested control-flow tasks exactly as the constraint validator does,
- * turns every `agent` string into a reference with the workflow as parent,
- * and asks the rule's one function — same clauses, same copy. It lives in
- * the workflow domain and not inside `InProcessValidator` because the
- * validator is pure over the spec by design and a rule that reads the
+ * agent as a STRING inside a `google.protobuf.Struct` config the generic
+ * spec walker cannot see, so the rule would never meet them. This step
+ * parses each task's config through the converter's own strict decoder
+ * (`unmarshalTaskConfig`, the one reader of a task config), walks nested
+ * control-flow tasks exactly as the constraint validator does, turns every
+ * `agent` string the write can judge into a reference with the workflow as
+ * parent, and asks the rule's one function — same clauses, same copy. It
+ * lives in the workflow domain and not inside `InProcessValidator` because
+ * the validator is pure over the spec by design and a rule that reads the
  * target's row cannot be.
  *
- * The parser here is STRICT: exactly `slug` or `org/slug`, both segments
- * non-empty, anything else refused at write naming the task. Two lenient
- * readers of the same string exist downstream and disagree with each other
- * (the runner's `parseAgentReference` in activities/call-agent.ts splits on
- * the first `/` and drops a third segment; the CLI's `parseReference` in
- * client-apps/cli/src/resources/reference.ts refuses a leading slash);
- * refusing every malformed shape here means neither ever meets one. The
- * three cannot share code — the packages share only the protos — so the
- * execution conformance suite is where their agreement is proven.
+ * The string has three forms (the `agent` field's contract in
+ * agent_call.proto), told apart by `classifyAgentReference`:
+ *
+ *   - `org/slug`, a LITERAL: judged now, like any stored reference;
+ *   - a bare `slug`, RELATIVE: the runner resolves it in the organization
+ *     the workflow runs in (`__stigmer_org_id`, the execution's), which is
+ *     not the workflow's when a person runs it from another organization by
+ *     id. It is judged now in the workflow's own organization with its
+ *     floor capped at org (references.ts, "RELATIVE");
+ *   - a value holding `${`, fixed only AT RUN: the runner's jq phase
+ *     (`${ expr }`, whole or embedded) or its activity phase
+ *     (`${.env_vars.KEY}`, `${.secrets.KEY}`) produces the reference when
+ *     the task runs. The write collects nothing for it; the run reads the
+ *     resolved agent as the person who ran the workflow, as it reads every
+ *     id-bound binding. The slug grammar (metadata.proto) can never contain
+ *     `${`, so the test is exact. It deliberately does not recognise only
+ *     the runner's shapes: that would be a second copy of the runner's
+ *     grammar in a package that shares only the protos with it, and a
+ *     mistyped expression already fails at run with the read's not-found.
+ *
+ * Anything else is refused at write naming the task. The runner's own
+ * parser (`parseAgentReference` in runner/src/activities/call-agent.ts) is
+ * lenient — it splits on the first `/` and drops a third segment — and the
+ * CLI's `parseReference` (client-apps/cli/src/resources/reference.ts)
+ * refuses a leading slash; refusing every malformed literal here means
+ * neither ever meets one. The three cannot share code; the conformance
+ * suites are where their agreement is proven.
  *
  * Runs after NormalizeReferences and ValidateReferences on the workflow
- * create and update chains, so the org the walk sees is the workflow's own
- * for a bare slug. Proven by __tests__/agent-call-references.test.ts and
- * the workflow conformance suite's reference arm.
+ * create and update chains, and feeds the workflow's escalation door
+ * (controller.ts). Proven by __tests__/agent-call-references.test.ts, the
+ * workflow conformance suite's agent_call reference arm, and the
+ * runner-as-subject execution arm for a reference fixed only at run.
  */
 import type { WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
 import type { AgentCallTaskConfig } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/tasks/agent_call_pb";
@@ -49,7 +68,7 @@ import { metadataOf } from "../../pipeline/steps/shapes.js";
 import { unmarshalTaskConfig } from "./converter/unmarshal.js";
 import { nestedTasks } from "./validation/task-config-constraints.js";
 
-/** The one sentence for an `agent` string that is neither `slug` nor `org/slug`. */
+/** The one sentence for an `agent` string that is none of the three forms. */
 export function malformedAgentReferenceMessage(
   taskName: string,
   agent: string,
@@ -57,29 +76,38 @@ export function malformedAgentReferenceMessage(
   return `task '${taskName}': agent '${agent}' is not a reference; write 'slug' for an agent of this organization or 'org/slug' for another organization's.`;
 }
 
-/**
- * `slug` or `org/slug` → the reference, with `org` empty for the bare form
- * (the caller fills the parent's). Returns undefined for any other shape.
- */
-export function parseAgentReference(
-  agent: string,
-): { readonly org: string; readonly slug: string } | undefined {
+/** What an `agent` string is before the rule reads it (the module header). */
+export type AgentReferenceForm =
+  | { readonly kind: "literal"; readonly org: string; readonly slug: string }
+  | { readonly kind: "relative"; readonly slug: string }
+  | { readonly kind: "run-time" }
+  | { readonly kind: "malformed" };
+
+/** Opens every runtime expression and placeholder the runner evaluates; never part of a slug. */
+const RUNTIME_EXPRESSION_MARKER = "${";
+
+export function classifyAgentReference(agent: string): AgentReferenceForm {
+  if (agent.includes(RUNTIME_EXPRESSION_MARKER)) {
+    return { kind: "run-time" };
+  }
   const parts = agent.split("/");
-  if (parts.length === 1) {
-    return parts[0] === "" ? undefined : { org: "", slug: parts[0]! };
+  if (parts.length === 1 && parts[0] !== "") {
+    return { kind: "relative", slug: parts[0]! };
   }
   if (parts.length === 2 && parts[0] !== "" && parts[1] !== "") {
-    return { org: parts[0]!, slug: parts[1]! };
+    return { kind: "literal", org: parts[0]!, slug: parts[1]! };
   }
-  return undefined;
+  return { kind: "malformed" };
 }
 
 /**
- * Every `agent_call` task's agent as a reference, nested tasks included in
- * declaration order, the bare form resolved to `parentOrg`. Throws
- * INVALID_ARGUMENT on the first malformed string. A config that does not
- * decode is skipped: the spec validation step has already refused the
- * workflow for it, and this collector never double-reports.
+ * Every `agent_call` task's agent the write can judge, as a reference,
+ * nested tasks included in declaration order: a literal as written, a
+ * relative slug in `parentOrg` and marked relative, a value fixed only at
+ * run not at all. Throws INVALID_ARGUMENT on the first malformed string. A
+ * config that does not decode is skipped: the spec validation step has
+ * already refused the workflow for it, and this collector never
+ * double-reports.
  */
 export function collectAgentCallReferences(
   spec: WorkflowSpec | undefined,
@@ -100,17 +128,36 @@ export function collectAgentCallReferences(
       if (config !== undefined) {
         if (task.kind === WorkflowTaskKind.agent_call) {
           const agent = (config as AgentCallTaskConfig).agent;
-          const parsed = parseAgentReference(agent);
-          if (parsed === undefined) {
-            throw invalidArgumentError(
-              malformedAgentReferenceMessage(task.name, agent),
-            );
+          const form = classifyAgentReference(agent);
+          switch (form.kind) {
+            case "literal":
+              refs.push({
+                kind: ApiResourceKind.agent,
+                org: form.org,
+                slug: form.slug,
+              });
+              break;
+            case "relative":
+              refs.push({
+                kind: ApiResourceKind.agent,
+                org: parentOrg,
+                slug: form.slug,
+                resolvesIn: "running-organization",
+              });
+              break;
+            case "run-time":
+              break;
+            case "malformed":
+              throw invalidArgumentError(
+                malformedAgentReferenceMessage(task.name, agent),
+              );
+            default: {
+              const exhaustive: never = form;
+              throw new Error(
+                `unknown agent reference form: ${JSON.stringify(exhaustive)}`,
+              );
+            }
           }
-          refs.push({
-            kind: ApiResourceKind.agent,
-            org: parsed.org === "" ? parentOrg : parsed.org,
-            slug: parsed.slug,
-          });
         }
         for (const nested of nestedTasks(config)) {
           visit(nested);

package/src/domain/workflow/registry/data/task-kind-registry.json

@@ -1362,7 +1362,7 @@
         {
           "name": "agent",
           "displayName": "Agent",
-          "description": "Agent reference in \"org/slug\" or \"slug\" format. - \"slug\" only: uses the workflow's organization - \"org/slug\": explicit organization reference Examples: \"code-reviewer\", \"stigmer/code-reviewer\", \"acme/data-analyst\" Required field.",
+          "description": "Agent to invoke, as \"slug\", \"org/slug\", or a value holding a runtime expression. - \"slug\": an agent of the organization the workflow runs in; checked when the workflow is saved, against the workflow's own organization - \"org/slug\": that organization's agent; checked when the workflow is saved, and another organization's agent must be shared at platform visibility - a value holding \"${ ... }\", \"${.env_vars.KEY}\" or \"${.secrets.KEY}\": resolved to \"slug\" or \"org/slug\" when the task runs, and read as the person who ran the workflow Examples: \"code-reviewer\", \"acme/data-analyst\", \"${.env_vars.TEAM_ORG}/assistant\" Required field.",
           "type": "string",
           "required": true,
           "groupId": "core",
@@ -1470,7 +1470,7 @@
         "additionalProperties": false,
         "properties": {
           "agent": {
-            "description": "Agent reference in \"org/slug\" or \"slug\" format. - \"slug\" only: uses the workflow's organization - \"org/slug\": explicit organization reference Examples: \"code-reviewer\", \"stigmer/code-reviewer\", \"acme/data-analyst\" Required field.",
+            "description": "Agent to invoke, as \"slug\", \"org/slug\", or a value holding a runtime expression. - \"slug\": an agent of the organization the workflow runs in; checked when the workflow is saved, against the workflow's own organization - \"org/slug\": that organization's agent; checked when the workflow is saved, and another organization's agent must be shared at platform visibility - a value holding \"${ ... }\", \"${.env_vars.KEY}\" or \"${.secrets.KEY}\": resolved to \"slug\" or \"org/slug\" when the task runs, and read as the person who ran the workflow Examples: \"code-reviewer\", \"acme/data-analyst\", \"${.env_vars.TEAM_ORG}/assistant\" Required field.",
             "maxLength": 127,
             "minLength": 1,
             "type": "string"