@stigmer/sdk 3.2.2 → 3.3.0

package/src/manifest/client.ts

@@ -0,0 +1,145 @@
+// Kind-agnostic apply/lookup over the manifest registry.
+//
+// One client, every registry kind: `apply` drives the kind's command
+// controller with the full resource proto (create-or-update by slug,
+// server-side), `getByReference` loads current server state for
+// create-vs-update previews and YAML editing.
+
+import type { Message } from "@bufbuild/protobuf";
+import { create } from "@bufbuild/protobuf";
+import type { DescService } from "@bufbuild/protobuf";
+import { createClient, type Client, type Transport } from "@connectrpc/connect";
+import { ApiResourceReferenceSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+import { wrapError } from "../gen/errors.js";
+import { metadataOf, type ManifestDocument } from "./parse.js";
+import {
+  manifestHandlerForYamlKind,
+  manifestKinds,
+  type ManifestKindHandler,
+  type ServiceClientFn,
+} from "./registry.js";
+
+/** Result of applying one manifest document. */
+export interface AppliedManifest {
+  /** The YAML kind that was applied, e.g. `"Agent"`. */
+  readonly yamlKind: string;
+  /** Human-facing kind name, e.g. `"MCP Server"`. */
+  readonly displayName: string;
+  /** Server-authoritative resource name. */
+  readonly name: string;
+  /** Server-authoritative slug (routing key for future applies). */
+  readonly slug: string;
+  /** Organization the resource lives in. */
+  readonly org: string;
+  /** Server-assigned resource id. */
+  readonly id: string;
+  /** The full applied resource, as returned by the server. */
+  readonly message: Message;
+}
+
+/**
+ * Client for applying and loading Stigmer resources as manifests,
+ * independent of kind.
+ *
+ * Complements the typed per-kind clients (`stigmer.agent`, …): those take
+ * curated `*Input` shapes for programmatic use; this one takes full
+ * resource protos produced by {@link parseManifest} — the declarative
+ * "apply this YAML" path, with the same semantics as `stigmer apply -f`.
+ *
+ * @example
+ * ```ts
+ * const docs = parseManifest(yamlText, { org: "acme" });
+ * for (const doc of docs) {
+ *   const applied = await stigmer.manifest.apply(doc);
+ *   console.log(`${applied.displayName} ${applied.slug} applied`);
+ * }
+ * ```
+ */
+export class ManifestClient {
+  // Raw controller clients are created lazily and cached per service —
+  // one dialog session typically touches one or two kinds.
+  private readonly clients = new Map<DescService, Client<DescService>>();
+  private readonly transport: Transport;
+  private readonly clientFor: ServiceClientFn;
+
+  constructor(transport: Transport) {
+    this.transport = transport;
+    this.clientFor = <Desc extends DescService>(service: Desc): Client<Desc> => {
+      let client = this.clients.get(service);
+      if (client === undefined) {
+        client = createClient(service, this.transport);
+        this.clients.set(service, client);
+      }
+      return client as Client<Desc>;
+    };
+  }
+
+  /** The kinds this client can apply, in dependency apply order. */
+  supportedKinds(): readonly ManifestKindHandler[] {
+    return manifestKinds();
+  }
+
+  /**
+   * Apply one parsed manifest document (create-or-update by slug).
+   *
+   * @throws {StigmerError} When the server rejects the apply
+   *   (validation, permissions, …).
+   */
+  async apply(document: ManifestDocument): Promise<AppliedManifest> {
+    let applied: Message;
+    try {
+      applied = await document.handler.apply(this.clientFor, document.message);
+    } catch (e) {
+      throw wrapError(e);
+    }
+
+    const metadata = metadataOf(applied);
+    return {
+      yamlKind: document.handler.yamlKind,
+      displayName: document.handler.displayName,
+      name: metadata?.name || document.name,
+      slug: metadata?.slug || document.slug,
+      org: metadata?.org || document.org,
+      id: metadata?.id ?? "",
+      message: applied,
+    };
+  }
+
+  /**
+   * Load a resource's current server state by kind + org/slug reference.
+   *
+   * @returns The resource proto, or `null` when it does not exist —
+   *   the create-vs-update discriminator for previews.
+   * @throws {Error} When the kind is not in the manifest registry.
+   * @throws {StigmerError} For failures other than not-found.
+   */
+  async getByReference(
+    yamlKind: string,
+    org: string,
+    slug: string,
+  ): Promise<Message | null> {
+    const handler = manifestHandlerForYamlKind(yamlKind);
+    if (handler === undefined) {
+      const supported = manifestKinds()
+        .map((h) => h.yamlKind)
+        .join(", ");
+      throw new Error(
+        `Unsupported resource kind "${yamlKind}". Supported kinds: ${supported}.`,
+      );
+    }
+
+    const ref = create(ApiResourceReferenceSchema, {
+      org,
+      slug,
+      kind: handler.kind,
+    });
+
+    try {
+      return await handler.getByReference(this.clientFor, ref);
+    } catch (e) {
+      const wrapped = wrapError(e);
+      if (wrapped.code === "not-found") return null;
+      throw wrapped;
+    }
+  }
+}

package/src/manifest/index.ts

@@ -0,0 +1,25 @@
+// Manifest engine: kind-agnostic YAML ⇄ proto ⇄ apply for Stigmer resources.
+//
+// The declarative counterpart to the typed per-kind clients — parse a YAML
+// manifest against generated proto schemas, serialize server state back to
+// editable YAML, and apply through each kind's command controller.
+
+export {
+  manifestKinds,
+  manifestHandlerForYamlKind,
+  manifestHandlerForTypeName,
+} from "./registry.js";
+export type { ManifestKindHandler, ServiceClientFn } from "./registry.js";
+
+export { parseManifest, metadataOf } from "./parse.js";
+export type { ManifestDocument, ParseManifestOptions } from "./parse.js";
+
+export { serializeManifest } from "./serialize.js";
+
+export { ManifestClient } from "./client.js";
+export type { AppliedManifest } from "./client.js";
+
+export {
+  REDACTED_SECRET_MARKER,
+  containsRedactedSecrets,
+} from "./redaction.js";

package/src/manifest/parse.ts

@@ -0,0 +1,204 @@
+// Strict YAML → proto parsing for Stigmer resource manifests.
+//
+// The strictness contract matches `stigmer apply -f`: YAML syntax errors and
+// unknown fields both fail loudly (`ignoreUnknownFields: false`) — silently
+// applying a half-parsed or typo'd document would be dangerous. Error
+// messages are written for end users (DD-006): what failed, where, and what
+// a valid document looks like.
+
+import { fromJson, type JsonValue, type Message } from "@bufbuild/protobuf";
+import { create } from "@bufbuild/protobuf";
+import {
+  type ApiResourceMetadata,
+  ApiResourceMetadataSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { parseAllDocuments } from "yaml";
+import {
+  type ManifestKindHandler,
+  manifestHandlerForYamlKind,
+  manifestKinds,
+} from "./registry.js";
+
+/** Options for {@link parseManifest}. */
+export interface ParseManifestOptions {
+  /**
+   * Target organization slug. Injected into `metadata.org` when the document
+   * omits it. When the document specifies a *different* org, the document's
+   * value wins and a warning is attached (matching `stigmer apply`).
+   */
+  readonly org?: string;
+}
+
+/** One resource document parsed from a manifest. */
+export interface ManifestDocument {
+  /** The registry handler for this document's kind. */
+  readonly handler: ManifestKindHandler;
+  /** The fully-marshalled resource proto, ready for `apply`. */
+  readonly message: Message;
+  /** `metadata.name` (always present — validated). */
+  readonly name: string;
+  /** `metadata.slug`, or the name when the document has no explicit slug. */
+  readonly slug: string;
+  /** `metadata.org` after org injection ("" when unresolvable). */
+  readonly org: string;
+  /** Org-mismatch warning, when the document's org differs from the target. */
+  readonly warning?: string;
+}
+
+/**
+ * Parse a (possibly multi-document) YAML manifest into resource protos.
+ *
+ * Each document is validated against its kind's generated proto schema —
+ * the same schemas the backend serves — so a document that parses here is
+ * structurally valid for `apply`. Documents are returned in **dependency
+ * apply order** (referenced kinds before dependents, stable within a kind),
+ * mirroring the CLI's apply ordering.
+ *
+ * @param content - Raw YAML text (one or more `---`-separated documents).
+ * @param options - Optional target org for `metadata.org` injection.
+ * @returns The parsed documents, sorted into dependency apply order.
+ * @throws {Error} With a user-facing message when the YAML is malformed,
+ *   a document has no `kind`, the kind is unsupported, or a document does
+ *   not match its proto schema (unknown fields included).
+ *
+ * @example
+ * ```ts
+ * import { parseManifest } from "@stigmer/sdk";
+ *
+ * const docs = parseManifest(yamlText, { org: "acme" });
+ * for (const doc of docs) {
+ *   await stigmer.manifest.apply(doc);
+ * }
+ * ```
+ */
+export function parseManifest(
+  content: string,
+  options: ParseManifestOptions = {},
+): ManifestDocument[] {
+  if (!content.trim()) {
+    throw new Error(
+      "The manifest is empty. Paste or upload a Stigmer resource YAML " +
+        "(a document with apiVersion, kind, metadata, and spec).",
+    );
+  }
+
+  const parsed = parseAllDocuments(content);
+  const documents: ManifestDocument[] = [];
+
+  for (const [index, doc] of parsed.entries()) {
+    const where = parsed.length === 1 ? "the manifest" : `document ${index + 1}`;
+
+    if (doc.errors.length > 0) {
+      throw new Error(`Invalid YAML in ${where}: ${doc.errors[0].message}`);
+    }
+
+    const value = doc.toJS() as unknown;
+    if (value === null || value === undefined) continue; // blank document between separators
+    if (typeof value !== "object" || Array.isArray(value)) {
+      throw new Error(
+        `Invalid YAML in ${where}: expected a mapping document with ` +
+          "apiVersion, kind, metadata, and spec.",
+      );
+    }
+
+    documents.push(parseDocument(value as Record<string, unknown>, where, options.org));
+  }
+
+  if (documents.length === 0) {
+    throw new Error(
+      "The manifest contains no resource documents. Each document needs " +
+        "at least a kind (e.g. kind: Agent) and metadata.name.",
+    );
+  }
+
+  // Stable sort into dependency order so multi-document manifests apply
+  // parents before dependents (e.g. Environment before AgentChannel).
+  return documents.sort((a, b) => a.handler.applyOrder - b.handler.applyOrder);
+}
+
+function parseDocument(
+  value: Record<string, unknown>,
+  where: string,
+  org: string | undefined,
+): ManifestDocument {
+  const kind = value.kind;
+  if (typeof kind !== "string" || kind === "") {
+    throw new Error(
+      `${capitalize(where)} is missing the required 'kind' field ` +
+        "(e.g. kind: Agent).",
+    );
+  }
+
+  const handler = manifestHandlerForYamlKind(kind);
+  if (handler === undefined) {
+    const supported = manifestKinds()
+      .map((h) => h.yamlKind)
+      .join(", ");
+    throw new Error(
+      `Unsupported resource kind "${kind}" in ${where}. ` +
+        `Supported kinds: ${supported}.`,
+    );
+  }
+
+  let message: Message;
+  try {
+    message = fromJson(handler.schema, value as JsonValue, {
+      ignoreUnknownFields: false,
+    });
+  } catch (err) {
+    throw new Error(
+      `Invalid ${handler.displayName} in ${where}: ${(err as Error).message}`,
+    );
+  }
+
+  const warning = injectOrg(message, org ?? "");
+
+  const metadata = metadataOf(message);
+  const name = metadata?.name ?? "";
+  if (name === "") {
+    throw new Error(
+      `${capitalize(where)} is missing the required metadata.name field.`,
+    );
+  }
+
+  return {
+    handler,
+    message,
+    name,
+    slug: metadata?.slug || name,
+    org: metadata?.org ?? "",
+    ...(warning !== undefined && { warning }),
+  };
+}
+
+/** Read a resource message's metadata envelope, if present. */
+export function metadataOf(message: Message): ApiResourceMetadata | undefined {
+  return (message as unknown as { metadata?: ApiResourceMetadata }).metadata;
+}
+
+// Inject the target org into metadata.org when the document omitted it. When
+// the document specifies a *different* org, the document's value is honored
+// and a warning is returned (matching `stigmer apply`).
+function injectOrg(message: Message, org: string): string | undefined {
+  if (org === "") return undefined;
+  const holder = message as unknown as { metadata?: ApiResourceMetadata };
+  if (holder.metadata === undefined) {
+    holder.metadata = create(ApiResourceMetadataSchema, { org });
+    return undefined;
+  }
+  if (holder.metadata.org === "") {
+    holder.metadata.org = org;
+    return undefined;
+  }
+  if (holder.metadata.org !== org) {
+    return (
+      `The document's org "${holder.metadata.org}" differs from the ` +
+      `target org "${org}"; applying to "${holder.metadata.org}".`
+    );
+  }
+  return undefined;
+}
+
+function capitalize(text: string): string {
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}

package/src/manifest/redaction.ts

@@ -0,0 +1,20 @@
+// The server-side secret-redaction contract, mirrored for client UX.
+
+/**
+ * Sentinel the server substitutes for secret values before they leave the
+ * backend (Cloud environment reads, ChannelApp/OAuthApp reads on both
+ * editions). Sending the marker back in an `apply` means "keep the stored
+ * secret" — the update pipelines restore the existing encrypted value.
+ */
+export const REDACTED_SECRET_MARKER = "***REDACTED***";
+
+/**
+ * Whether manifest content contains redacted secret values.
+ *
+ * Used by editing UIs to explain the marker to users ("redacted secrets
+ * keep their stored values when applied") instead of letting it read like
+ * a bug.
+ */
+export function containsRedactedSecrets(content: string): boolean {
+  return content.includes(REDACTED_SECRET_MARKER);
+}

package/src/manifest/registry.ts

@@ -0,0 +1,232 @@
+// Explicit manifest-kind registry: the single place that binds a YAML `kind`
+// to its proto schema and controller RPCs.
+//
+// This is the SDK home of the pattern the CLIs already rely on (Go CLI,
+// TS CLI `resources/apply/handlers.ts`, mcp-server): strict YAML→proto
+// marshalling against the *generated schema*, and apply through the raw
+// command controller with the full resource message. The high-level
+// `*Input` wrappers are intentionally bypassed — they are lossy (they drop
+// `metadata.id` and any field codegen hasn't projected), while the `apply`
+// RPC takes the complete resource and the server upserts by slug.
+//
+// Registration is explicit — to support a new kind, add one entry here.
+
+import type { DescMessage, DescService, Message } from "@bufbuild/protobuf";
+import type { Client } from "@connectrpc/connect";
+import { ApiResourceKind } from "@stigmer/protos/ai/stigmer/commons/apiresource/apiresourcekind/api_resource_kind_pb";
+import type { ApiResourceReference } from "@stigmer/protos/ai/stigmer/commons/apiresource/io_pb";
+
+import { type Agent, AgentSchema } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { AgentCommandController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/command_pb";
+import { AgentQueryController } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/query_pb";
+import { type AgentChannel, AgentChannelSchema } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/api_pb";
+import { AgentChannelCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/command_pb";
+import { AgentChannelQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentchannel/v1/query_pb";
+import { type AgentInstance, AgentInstanceSchema } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/api_pb";
+import { AgentInstanceCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/command_pb";
+import { AgentInstanceQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentinstance/v1/query_pb";
+import { type AgentShare, AgentShareSchema } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/api_pb";
+import { AgentShareCommandController } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/command_pb";
+import { AgentShareQueryController } from "@stigmer/protos/ai/stigmer/agentic/agentshare/v1/query_pb";
+import { type ChannelApp, ChannelAppSchema } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/api_pb";
+import { ChannelAppCommandController } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/command_pb";
+import { ChannelAppQueryController } from "@stigmer/protos/ai/stigmer/agentic/channelapp/v1/query_pb";
+import { type Datastore, DatastoreSchema } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/api_pb";
+import { DatastoreCommandController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/command_pb";
+import { DatastoreQueryController } from "@stigmer/protos/ai/stigmer/agentic/datastore/v1/query_pb";
+import { type Environment, EnvironmentSchema } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { EnvironmentCommandController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/command_pb";
+import { EnvironmentQueryController } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/query_pb";
+import { type McpServer, McpServerSchema } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/api_pb";
+import { McpServerCommandController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/command_pb";
+import { McpServerQueryController } from "@stigmer/protos/ai/stigmer/agentic/mcpserver/v1/query_pb";
+import { type Workflow, WorkflowSchema } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/api_pb";
+import { WorkflowCommandController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/command_pb";
+import { WorkflowQueryController } from "@stigmer/protos/ai/stigmer/agentic/workflow/v1/query_pb";
+import { type IdentityProvider, IdentityProviderSchema } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/api_pb";
+import { IdentityProviderCommandController } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/command_pb";
+import { IdentityProviderQueryController } from "@stigmer/protos/ai/stigmer/iam/identityprovider/v1/query_pb";
+import { type OAuthApp, OAuthAppSchema } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/api_pb";
+import { OAuthAppCommandController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/command_pb";
+import { OAuthAppQueryController } from "@stigmer/protos/ai/stigmer/iam/oauthapp/v1/query_pb";
+
+/**
+ * Accessor for a raw Connect client over a generated service controller.
+ * Implementations cache clients per service (see `ManifestClient`).
+ */
+export type ServiceClientFn = <Desc extends DescService>(service: Desc) => Client<Desc>;
+
+/**
+ * Binds one YAML `kind` to everything the manifest engine needs:
+ * the proto schema (strict marshalling), the command controller's `apply`
+ * RPC, and the query controller's `getByReference` RPC (create-vs-update
+ * preview).
+ */
+export interface ManifestKindHandler {
+  /** The platform resource kind enum value. */
+  readonly kind: ApiResourceKind;
+  /** The YAML discriminator, e.g. `"Agent"`. */
+  readonly yamlKind: string;
+  /** Human-facing name for messages, e.g. `"MCP Server"`. */
+  readonly displayName: string;
+  /** Canonical `apiVersion` for this kind, e.g. `"agentic.stigmer.ai/v1"`. */
+  readonly apiVersion: string;
+  /** Proto schema for strict YAML↔proto conversion. */
+  readonly schema: DescMessage;
+  /**
+   * Position in the dependency apply order (ascending). Referenced kinds
+   * apply before their dependents, e.g. an McpServer before the Agent that
+   * uses it, and everything an AgentChannel references before the channel.
+   */
+  readonly applyOrder: number;
+  /** Drive the command controller's `apply` RPC with the full resource. */
+  apply(clientFor: ServiceClientFn, message: Message): Promise<Message>;
+  /** Load the current server state by org/slug reference. */
+  getByReference(clientFor: ServiceClientFn, ref: ApiResourceReference): Promise<Message>;
+}
+
+const AGENTIC_V1 = "agentic.stigmer.ai/v1";
+const IAM_V1 = "iam.stigmer.ai/v1";
+
+const HANDLERS: readonly ManifestKindHandler[] = [
+  {
+    kind: ApiResourceKind.mcp_server,
+    yamlKind: "McpServer",
+    displayName: "MCP Server",
+    apiVersion: AGENTIC_V1,
+    schema: McpServerSchema,
+    applyOrder: 1,
+    apply: (c, m) => c(McpServerCommandController).apply(m as McpServer),
+    getByReference: (c, ref) => c(McpServerQueryController).getByReference(ref),
+  },
+  // A Datastore applies before the Agents that reference it via
+  // datastore_usages (the McpServer-before-Agent pattern).
+  {
+    kind: ApiResourceKind.datastore,
+    yamlKind: "Datastore",
+    displayName: "Datastore",
+    apiVersion: AGENTIC_V1,
+    schema: DatastoreSchema,
+    applyOrder: 2,
+    apply: (c, m) => c(DatastoreCommandController).apply(m as Datastore),
+    getByReference: (c, ref) => c(DatastoreQueryController).getByReference(ref),
+  },
+  {
+    kind: ApiResourceKind.agent,
+    yamlKind: "Agent",
+    displayName: "Agent",
+    apiVersion: AGENTIC_V1,
+    schema: AgentSchema,
+    applyOrder: 3,
+    apply: (c, m) => c(AgentCommandController).apply(m as Agent),
+    getByReference: (c, ref) => c(AgentQueryController).getByReference(ref),
+  },
+  {
+    kind: ApiResourceKind.workflow,
+    yamlKind: "Workflow",
+    displayName: "Workflow",
+    apiVersion: AGENTIC_V1,
+    schema: WorkflowSchema,
+    applyOrder: 4,
+    apply: (c, m) => c(WorkflowCommandController).apply(m as Workflow),
+    getByReference: (c, ref) => c(WorkflowQueryController).getByReference(ref),
+  },
+  {
+    kind: ApiResourceKind.environment,
+    yamlKind: "Environment",
+    displayName: "Environment",
+    apiVersion: AGENTIC_V1,
+    schema: EnvironmentSchema,
+    applyOrder: 5,
+    apply: (c, m) => c(EnvironmentCommandController).apply(m as Environment),
+    getByReference: (c, ref) => c(EnvironmentQueryController).getByReference(ref),
+  },
+  {
+    kind: ApiResourceKind.identity_provider,
+    yamlKind: "IdentityProvider",
+    displayName: "Identity Provider",
+    apiVersion: IAM_V1,
+    schema: IdentityProviderSchema,
+    applyOrder: 6,
+    apply: (c, m) => c(IdentityProviderCommandController).apply(m as IdentityProvider),
+    getByReference: (c, ref) => c(IdentityProviderQueryController).getByReference(ref),
+  },
+  {
+    kind: ApiResourceKind.oauth_app,
+    yamlKind: "OAuthApp",
+    displayName: "OAuth App",
+    apiVersion: IAM_V1,
+    schema: OAuthAppSchema,
+    applyOrder: 7,
+    apply: (c, m) => c(OAuthAppCommandController).apply(m as OAuthApp),
+    getByReference: (c, ref) => c(OAuthAppQueryController).getByReference(ref),
+  },
+  {
+    kind: ApiResourceKind.channel_app,
+    yamlKind: "ChannelApp",
+    displayName: "Channel App",
+    apiVersion: AGENTIC_V1,
+    schema: ChannelAppSchema,
+    applyOrder: 8,
+    apply: (c, m) => c(ChannelAppCommandController).apply(m as ChannelApp),
+    getByReference: (c, ref) => c(ChannelAppQueryController).getByReference(ref),
+  },
+  {
+    kind: ApiResourceKind.agent_instance,
+    yamlKind: "AgentInstance",
+    displayName: "Agent Instance",
+    apiVersion: AGENTIC_V1,
+    schema: AgentInstanceSchema,
+    applyOrder: 9,
+    apply: (c, m) => c(AgentInstanceCommandController).apply(m as AgentInstance),
+    getByReference: (c, ref) => c(AgentInstanceQueryController).getByReference(ref),
+  },
+  {
+    kind: ApiResourceKind.agent_share,
+    yamlKind: "AgentShare",
+    displayName: "Agent Share",
+    apiVersion: AGENTIC_V1,
+    schema: AgentShareSchema,
+    applyOrder: 10,
+    apply: (c, m) => c(AgentShareCommandController).apply(m as AgentShare),
+    getByReference: (c, ref) => c(AgentShareQueryController).getByReference(ref),
+  },
+  // Last: an AgentChannel references an Agent, a ChannelApp, and Environments.
+  {
+    kind: ApiResourceKind.agent_channel,
+    yamlKind: "AgentChannel",
+    displayName: "Agent Channel",
+    apiVersion: AGENTIC_V1,
+    schema: AgentChannelSchema,
+    applyOrder: 11,
+    apply: (c, m) => c(AgentChannelCommandController).apply(m as AgentChannel),
+    getByReference: (c, ref) => c(AgentChannelQueryController).getByReference(ref),
+  },
+];
+
+const BY_YAML_KIND: ReadonlyMap<string, ManifestKindHandler> = new Map(
+  HANDLERS.map((h) => [h.yamlKind, h]),
+);
+
+const BY_TYPE_NAME: ReadonlyMap<string, ManifestKindHandler> = new Map(
+  HANDLERS.map((h) => [h.schema.typeName, h]),
+);
+
+/** All kinds the manifest engine supports, in dependency apply order. */
+export function manifestKinds(): readonly ManifestKindHandler[] {
+  return HANDLERS;
+}
+
+/** Resolve a handler by its YAML `kind` discriminator (e.g. `"Agent"`). */
+export function manifestHandlerForYamlKind(
+  yamlKind: string,
+): ManifestKindHandler | undefined {
+  return BY_YAML_KIND.get(yamlKind);
+}
+
+/** Resolve a handler from a proto message's fully-qualified type name. */
+export function manifestHandlerForTypeName(
+  typeName: string,
+): ManifestKindHandler | undefined {
+  return BY_TYPE_NAME.get(typeName);
+}