@stigmer/server 3.21.0 → 3.22.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/server",
-  "version": "3.21.0",
+  "version": "3.22.0",
   "description": "The Stigmer OSS control plane as a composable library: composeServer, the extension registry and the driver seams a composition builds on. The self-contained deployable of the same server is @stigmer/server-slim.",
   "license": "Apache-2.0",
   "type": "module",
@@ -62,11 +62,11 @@
     "@connectrpc/connect-node": "^2.0.0",
     "@kubernetes/client-node": "2.0.0",
     "@opentelemetry/api": "^1.9.0",
-    "@stigmer/outbound": "3.21.0",
-    "@stigmer/plugin-package": "3.21.0",
-    "@stigmer/protos": "3.21.0",
-    "@stigmer/temporal-codecs": "3.21.0",
-    "@stigmer/zip-structure": "3.21.0",
+    "@stigmer/outbound": "3.22.0",
+    "@stigmer/plugin-package": "3.22.0",
+    "@stigmer/protos": "3.22.0",
+    "@stigmer/temporal-codecs": "3.22.0",
+    "@stigmer/zip-structure": "3.22.0",
     "@temporalio/activity": "1.16.2",
     "@temporalio/client": "1.16.2",
     "@temporalio/common": "1.16.2",

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

@@ -17,7 +17,9 @@
  * org-observable reaches the organization's viewers; a memory with no
  * subject is nobody's; an instance reaches whoever reads its blueprint
  * only when it is the default. Then the contract: a scope only narrows
- * and never reorders; the `internal` class is the in-process skip; an
+ * and never reorders; the `internal` class is the in-process skip on the
+ * enumeration verb and a loud consumer bug on the restrict verb (the
+ * shared helper answers the class before any driver, stigmer#1207); an
  * unprovisioned subject is their raw subject (the 3.14 verifiers' stamp); a
  * fault throws and is never an empty answer; an undeclared kind is a
  * consumer bug, loud; the enumeration verb equals the restrict verb over
@@ -583,17 +585,7 @@ describe.each(driverFixtures(SEEDED_KINDS))(
             expect(accountReads).toBe(0);
           });
 
-          it("the `internal` class — the server acting as itself — keeps every offered id and enumerates every id of the kind: the in-process authorization skip, with no account even asked for", async () => {
-            const offered = rowsOf(ApiResourceKind.agent).map((row) =>
-              entryOf(ApiResourceKind.agent, row),
-            );
-            expect([
-              ...(await scope().restrictListEntries(
-                INTERNAL,
-                ApiResourceKind.agent,
-                offered,
-              )),
-            ]).toEqual(offered.map((entry) => entry.id));
+          it("the `internal` class on the enumeration verb — the server acting as itself — is every id of the kind, with no account even asked for (the in-process skip; no helper stands before this verb)", async () => {
             expect(
               [
                 ...(await scope().authorizedResourceIds(
@@ -605,6 +597,25 @@ describe.each(driverFixtures(SEEDED_KINDS))(
             expect(accountReads).toBe(0);
           });
 
+          it("the `internal` class on the restrict verb is a consumer bug, loud: the shared helper answers that class before any driver, so a driver offered it was reached around the idiom", async () => {
+            const offered = rowsOf(ApiResourceKind.agent).map((row) =>
+              entryOf(ApiResourceKind.agent, row),
+            );
+            const refusal = await scope()
+              .restrictListEntries(INTERNAL, ApiResourceKind.agent, offered)
+              .then(
+                () => undefined,
+                (error: unknown) => error,
+              );
+            expect(refusal).toBeInstanceOf(AuthorizationEvaluationError);
+            expect((refusal as AuthorizationEvaluationError).reason).toBe(
+              "internal-caller-offered",
+            );
+            // Refused before any read: the server was never evaluated as a person.
+            expect(accountReads).toBe(0);
+            expect(storeReads).toEqual({ rows: 0, scans: 0 });
+          });
+
           it("an unprovisioned subject is their raw subject and nothing else: the 3.14-stamped row is theirs, the organization's rows are not", async () => {
             // `agt_legacy` is stamped with LEGACY's raw subject; a caller
             // who IS that subject and holds no account reaches it through

package/src/authorization/__tests__/skip-lane-inventory.test.ts

@@ -0,0 +1,160 @@
+/**
+ * Pins the coverage inventory's own rule for `is_skip_authorization` lanes
+ * (docs/authorization-coverage.md, "How to read the tables"): a skip lane
+ * reaches no Authorizer in either edition, so what guards it is whatever
+ * its Handler cell names — and a cell that names nothing is a lane open to
+ * every authenticated caller that nobody has said so about. Two things are
+ * held here, so the doc cannot drift from the server it describes:
+ *
+ *   1. The set of skip-annotated methods the open-source server SERVES
+ *      (the empty composition's routes replayed into a recorder, a method
+ *      counted only when its service's implementation map carries it — a
+ *      partially implemented service lists more on its descriptor than it
+ *      serves) equals the set of skip rows in the doc, service by method.
+ *      A new skip lane without a row, or a row for a lane that is no
+ *      longer a skip, fails here.
+ *   2. Every skip row's Handler cell carries one of the three markers the
+ *      doc defines — `guard: <Name>`, `driver: <Seam>`,
+ *      `by design: <reason>` — and every `guard:` names a pipeline step or
+ *      a handler's guard function that exists by that name in `src/`
+ *      outside the tests, so a renamed or removed guard cannot leave the
+ *      doc pointing at nothing.
+ *
+ * The rule lives in the doc; this test only enforces it. The doc is the
+ * one inventory (the package guide mandates updating it with every
+ * annotation change), and a second list here would be the drift this
+ * test exists to prevent.
+ */
+import {
+  mkdtempSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { getOption } from "@bufbuild/protobuf";
+import { afterAll, beforeAll, describe, expect, it } from "vitest";
+
+import { is_skip_authorization } from "@stigmer/protos/ai/stigmer/commons/rpc/method_options_pb";
+
+import { loadConfig } from "../../boot/config.js";
+import { composeServer } from "../../boot/compose.js";
+import type { ComposedServer } from "../../boot/compose.js";
+import {
+  baseConfig,
+  servedMethods,
+  silentLogger,
+} from "../../extensions/__tests__/composed-support.js";
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE_ROOT = path.resolve(HERE, "../../..");
+const COVERAGE_DOC = path.join(PACKAGE_ROOT, "docs/authorization-coverage.md");
+const SRC = path.join(PACKAGE_ROOT, "src");
+
+/** A skip row: `| Service.method | is_skip_authorization | <handler cell> |`. */
+const SKIP_ROW =
+  /^\| ([A-Za-z]+)\.([A-Za-z]+) \| is_skip_authorization \| (.*) \|$/;
+
+const MARKERS = ["guard:", "driver:", "by design:"] as const;
+
+interface SkipRow {
+  readonly method: string;
+  readonly handler: string;
+}
+
+function skipRowsOf(doc: string): SkipRow[] {
+  const rows: SkipRow[] = [];
+  for (const line of doc.split("\n")) {
+    const m = SKIP_ROW.exec(line);
+    if (m !== null) {
+      rows.push({ method: `${m[1]}.${m[2]}`, handler: m[3] ?? "" });
+    }
+  }
+  return rows;
+}
+
+/** Every `guard: <Name>` a handler cell names. */
+function guardsOf(handler: string): string[] {
+  return [...handler.matchAll(/guard: ([A-Za-z]+)/g)].map((m) => m[1] ?? "");
+}
+
+/** Every non-test `.ts` source under `src/`, read once. */
+function sourceText(): string {
+  const parts: string[] = [];
+  const walk = (dir: string): void => {
+    for (const entry of readdirSync(dir)) {
+      const full = path.join(dir, entry);
+      if (statSync(full).isDirectory()) {
+        if (entry !== "__tests__") {
+          walk(full);
+        }
+      } else if (full.endsWith(".ts") && !full.endsWith(".test.ts")) {
+        parts.push(readFileSync(full, "utf8"));
+      }
+    }
+  };
+  walk(SRC);
+  return parts.join("\n");
+}
+
+describe("the skip-lane inventory (docs/authorization-coverage.md) is true to the served server", () => {
+  let dir: string;
+  let server: ComposedServer;
+
+  beforeAll(async () => {
+    dir = mkdtempSync(path.join(tmpdir(), "skip-lane-inventory-test-"));
+    server = await composeServer({
+      config: loadConfig(baseConfig(dir)),
+      logger: silentLogger,
+      portOverride: 0,
+      host: "127.0.0.1",
+    });
+  });
+
+  afterAll(async () => {
+    await server.shutdown();
+    rmSync(dir, { recursive: true, force: true });
+  });
+
+  it("the doc's skip rows are exactly the skip-annotated methods the server serves", () => {
+    const served = new Set<string>();
+    for (const method of servedMethods(server.routes)) {
+      if (getOption(method, is_skip_authorization)) {
+        const serviceName = method.parent.typeName.split(".").at(-1) ?? "";
+        served.add(`${serviceName}.${method.name}`);
+      }
+    }
+    const documented = new Set(
+      skipRowsOf(readFileSync(COVERAGE_DOC, "utf8")).map((r) => r.method),
+    );
+    expect([...served].sort()).toEqual([...documented].sort());
+  });
+
+  it("every skip row names its guard, its driver or says the lane is open by design", () => {
+    const bare = skipRowsOf(readFileSync(COVERAGE_DOC, "utf8"))
+      .filter((r) => !MARKERS.some((marker) => r.handler.includes(marker)))
+      .map((r) => r.method);
+    expect(bare).toEqual([]);
+  });
+
+  it("every guard a skip row names is a step or a guard function that exists by that name in src/", () => {
+    const source = sourceText();
+    const dangling: string[] = [];
+    for (const row of skipRowsOf(readFileSync(COVERAGE_DOC, "utf8"))) {
+      for (const guard of guardsOf(row.handler)) {
+        // A step is registered by its quoted name; a guard function by its
+        // declaration.
+        const isStep = source.includes(`"${guard}"`);
+        const isFunction = new RegExp(`function ${guard}\\(`).test(source);
+        if (!isStep && !isFunction) {
+          dangling.push(`${row.method} names guard ${guard}`);
+        }
+      }
+    }
+    expect(dangling).toEqual([]);
+  });
+});

package/src/authorization/__tests__/wire-permissions.test.ts

@@ -117,12 +117,11 @@ describe("every static (kind, permission) the served RPCs ask about is a declare
     expect(undeclared).toEqual([]);
   });
 
-  it("asks about every served kind the model declares except the two no RPC targets statically", () => {
+  it("asks about every served kind the model declares except the one no RPC targets statically", () => {
     // iam_policy's RPCs target the policy's RESOURCE (`resource_kind_path`
-    // or the load-then-authorize `get`); execution_context's RPCs are
-    // `is_skip_authorization` lanes (or unannotated) whose handlers gate on
-    // the runner's execution-scoped token. Every other declared kind is
-    // asked about by at least one static annotation.
+    // or the load-then-authorize `get`). Every other declared kind is asked
+    // about by at least one static annotation — execution_context through
+    // its `get` and `delete`; its runner-token lane stays a skip.
     const asked = new Set(wireQuestions().map((q) => kindEnumName(q.kind)));
     expect([...asked].sort()).toEqual(
       [
@@ -135,6 +134,7 @@ describe("every static (kind, permission) the served RPCs ask about is a declare
         "artifact",
         "channel_app",
         "environment",
+        "execution_context",
         "identity_account",
         "mcp_server",
         "memory",

package/src/authorization/evaluator.ts

@@ -67,8 +67,15 @@ import {
  */
 export const MAX_RESOLUTION_DEPTH = 25;
 
+/**
+ * The faults an evaluation can raise. Two are consumer bugs by the seam
+ * contracts (a kind the model does not declare; the `internal` class
+ * offered to the list scope's restrict verb, which the shared helper
+ * answers before any driver); the rest are the model's own.
+ */
 export type EvaluationFault =
   | "undeclared-target-kind"
+  | "internal-caller-offered"
   | "resolution-depth-exceeded"
   | "resolution-cycle"
   | "unknown-condition";

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

@@ -38,17 +38,25 @@
  *     lane can show it either.
  *
  * The `internal` class — the server acting as itself over the in-process
- * transport — keeps every offered id and enumerates every id of the kind:
- * the in-process authorization skip (pipeline/interceptors/auth.ts, ruling
- * Q4) applied to a list answer, as the built-in directory applies it to a
- * directory answer. No in-process edge reaches a list lane today; the arm
- * is pinned so a future one meets the same rule every other lane keeps.
+ * transport — is answered by the seam, not here: `restrictListByReadScope`
+ * returns the org-narrowed rows for the class before any driver is asked
+ * (extensions/list-read-scope.ts, the header's contract line), the
+ * Authorize step's trust-domain rule applied to a list answer. So this
+ * driver's `restrictListEntries` REFUSES the class (`internal-caller-offered`):
+ * being offered it means a caller reached the driver around the one
+ * consumption idiom, and evaluating the server as a person would return
+ * a quiet short list — the failure shape stigmer#1207 fixed. The
+ * enumeration verb has no helper in front of it and keeps its own arm:
+ * every id of the kind, as the built-in directory answers the class with
+ * every organization. No in-process edge reaches an enumeration lane
+ * today; the arm is pinned so a future one meets the rule.
  *
  * Faults THROW and are never an empty answer (the seam: an empty set means
  * "authorized to see nothing"; an outage is the pipeline's sanitized
- * INTERNAL). A kind the model does not declare is a consumer bug by the
- * seam's contract and faults through the evaluator, loud; the model
- * declares exactly the open-source tier, so no served lane can reach it.
+ * INTERNAL). A kind the model does not declare, like the internal class
+ * above, is a consumer bug by the seam's contract and faults through the
+ * evaluator, loud; the model declares exactly the open-source tier, so no
+ * served lane can reach it.
  *
  * Logging. One debug line per call — kind, offered, kept, elapsed — what
  * an operator needs to answer "why is Alice's list short" beside the
@@ -188,6 +196,12 @@ export function newBuiltInListReadScope(
       entries: ReadonlyArray<ListEntryMeta>,
     ): Promise<ReadonlySet<string>> {
       requireDeclared(kind);
+      if (caller.callerClass === "internal") {
+        throw new AuthorizationEvaluationError(
+          "internal-caller-offered",
+          `the internal caller class was offered to the list scope for kind '${kindEnumName(kind)}' — the shared helper answers that class before any driver; a list lane reached the driver around it`,
+        );
+      }
       // One candidate per unique id: a lane offers each row once, and a
       // duplicate would only spend a walk to learn the same answer.
       const unique = new Map<string, RowFacts>();
@@ -196,9 +210,6 @@ export function newBuiltInListReadScope(
           unique.set(entry.id, rowFactsOfEntry(kind, entry));
         }
       }
-      if (caller.callerClass === "internal") {
-        return new Set(unique.keys());
-      }
       return visibleAmong(caller, kind, [...unique.values()]);
     },
 

package/src/authorization/model/__tests__/registry.test.ts

@@ -104,6 +104,7 @@ const WIRE_PERMISSIONS_BY_TYPE: Readonly<
     "can_create_environment",
     "can_create_skill",
     "can_create_plugin",
+    "can_create_mcp_server",
     "can_create_idp",
     "can_create_identity_account",
     "can_create_oauth_app",
@@ -111,6 +112,7 @@ const WIRE_PERMISSIONS_BY_TYPE: Readonly<
     "can_create_channel_app",
     "can_create_execution_in",
     "can_create_agent_share",
+    "can_create_agent_instance",
     "can_grant_access",
     "can_view_access",
     "can_view_billing",

package/src/authorization/model/organization.ts

@@ -39,6 +39,7 @@ export const organizationDeclaration = declareKind({
     ["can_create_environment", computed("member")],
     ["can_create_skill", computed("admin")],
     ["can_create_plugin", computed("admin")],
+    ["can_create_mcp_server", computed("admin")],
     ["can_create_idp", computed("admin")],
     ["can_create_identity_account", computed("admin")],
     ["can_create_oauth_app", computed("admin")],
@@ -46,6 +47,7 @@ export const organizationDeclaration = declareKind({
     ["can_create_channel_app", computed("admin")],
     ["can_create_execution_in", union(computed("member"), computed("guest"))],
     ["can_create_agent_share", computed("admin")],
+    ["can_create_agent_instance", computed("member")],
     ["can_grant_access", computed("admin")],
     ["can_view_access", computed("viewer")],
     ["can_view_billing", computed("viewer")],

package/src/domain/agent/controller.ts

@@ -37,6 +37,10 @@ import type { PipelineStep } 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 {
+  loadedTargetAsMethod,
+  newAuthorizeResolvedTargetStep,
+} from "../../pipeline/steps/authorize-resolved-target.js";
 import { newGuardReservedLabelsStep } from "../../pipeline/steps/guard-reserved-labels.js";
 import {
   newAuthorizeVisibilityTransitionStep,
@@ -527,6 +531,12 @@ async function getByReference(
     )
     .addStep(newValidateProtoStep())
     .addStep(newLoadByReferenceStep(deps.store, AgentSchema))
+    .addStep(
+      newAuthorizeResolvedTargetStep(
+        deps.authorizer,
+        loadedTargetAsMethod(AgentQueryController.method.get),
+      ),
+    )
     .build()
     .execute(reqCtx);
   return reqCtx.get(TARGET_RESOURCE_KEY) as Agent;

package/src/domain/agentchannel/__tests__/create-authorization.test.ts

@@ -0,0 +1,58 @@
+/**
+ * Pins the create lane's authorization question (steps.ts,
+ * resolveChannelCreateTargets): can_edit on the REFERENCED AGENT with the
+ * Java handler's copy, and nothing on the organization (the same-org
+ * invariant already binds the channel to the agent's); a missing
+ * referenced agent throws.
+ */
+import { describe, expect, it } from "vitest";
+import { create } from "@bufbuild/protobuf";
+
+import { AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentChannelSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/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 { testCallerIdentity } from "../../../pipeline/__tests__/support.js";
+import { RequestContext } from "../../../pipeline/request-context.js";
+import {
+  CHANNEL_CREATE_DENIED_MESSAGE,
+  REFERENCED_AGENT_KEY,
+  resolveChannelCreateTargets,
+} from "../steps.js";
+
+const agent = create(AgentSchema, {
+  metadata: { id: "agt_01target", name: "helper", org: "acme" },
+});
+
+function ctxFor(stash = true) {
+  const ctx = new RequestContext(
+    AgentChannelSchema,
+    create(AgentChannelSchema, { metadata: { name: "support", org: "acme" } }),
+    testCallerIdentity(),
+    ApiResourceKind.agent_channel,
+  );
+  if (stash) {
+    ctx.set(REFERENCED_AGENT_KEY, agent);
+  }
+  return ctx;
+}
+
+describe("resolveChannelCreateTargets", () => {
+  it("asks can_edit on the referenced agent and nothing else", () => {
+    expect(resolveChannelCreateTargets(ctxFor())).toEqual([
+      {
+        permission: IamPermission.can_edit,
+        resourceKind: ApiResourceKind.agent,
+        resourceId: "agt_01target",
+        deniedMessage: CHANNEL_CREATE_DENIED_MESSAGE,
+      },
+    ]);
+  });
+
+  it("a missing referenced agent is a broken chain invariant and throws", () => {
+    expect(() => resolveChannelCreateTargets(ctxFor(false))).toThrow(
+      "referenced agent not found in context",
+    );
+  });
+});

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