@stigmer/sdk 3.2.3 → 3.4.0

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);
+}

package/src/manifest/serialize.ts

@@ -0,0 +1,92 @@
+// Proto → canonical Stigmer YAML serialization.
+//
+// Follows the platform-wide protojson parity contract (Go CLI, TS CLI
+// output/proto.ts, mcp-server marshal.ts): `toJson` with
+// `useProtoFieldName: true` emits snake_case field names and omits unset
+// defaults, so the output round-trips through `parseManifest`'s strict
+// `fromJson` without loss.
+//
+// Two deliberate departures from the raw protojson projection, both for
+// the *editable manifest* use case:
+//   - `status` and `metadata.version` are stripped — they are system-managed
+//     and would be ignored (or rejected) on apply.
+//   - the envelope field is spelled `apiVersion` (the canonical form used in
+//     every repo manifest and doc); `fromJson` accepts both spellings.
+
+import { toJson, type Message } from "@bufbuild/protobuf";
+import { stringify as stringifyYaml } from "yaml";
+import { manifestHandlerForTypeName, manifestKinds } from "./registry.js";
+
+/**
+ * Serialize a resource proto into the canonical, editable Stigmer YAML form.
+ *
+ * The resource kind is derived from the message's proto type, so any
+ * registry-supported resource (an `Agent` from `stigmer.agent.get()`, an
+ * `Environment` from `stigmer.environment.get()`, …) serializes with the
+ * same call. `metadata.id` is preserved — the output is a full-fidelity
+ * representation of the stored resource, minus system-managed state.
+ *
+ * @param message - A resource proto of a registry-supported kind.
+ * @returns YAML text suitable for editing and re-applying.
+ * @throws {Error} When the message's kind is not in the manifest registry.
+ *
+ * @example
+ * ```ts
+ * import { serializeManifest } from "@stigmer/sdk";
+ *
+ * const agent = await stigmer.agent.get(agentId);
+ * const yaml = serializeManifest(agent);
+ * ```
+ */
+export function serializeManifest(message: Message): string {
+  const handler = manifestHandlerForTypeName(message.$typeName);
+  if (handler === undefined) {
+    const supported = manifestKinds()
+      .map((h) => h.yamlKind)
+      .join(", ");
+    throw new Error(
+      `Cannot serialize ${message.$typeName} as a manifest: kind is not ` +
+        `in the manifest registry. Supported kinds: ${supported}.`,
+    );
+  }
+
+  const json = toJson(handler.schema, message, { useProtoFieldName: true });
+  if (json === null || typeof json !== "object" || Array.isArray(json)) {
+    throw new Error(
+      `Cannot serialize ${handler.displayName}: unexpected non-object ` +
+        "protojson projection.",
+    );
+  }
+
+  const { api_version, kind, status, metadata, ...rest } =
+    json as Record<string, unknown>;
+  void status;
+
+  const doc: Record<string, unknown> = {
+    apiVersion: typeof api_version === "string" && api_version !== ""
+      ? api_version
+      : handler.apiVersion,
+    kind: typeof kind === "string" && kind !== "" ? kind : handler.yamlKind,
+    ...(isPlainObject(metadata) && { metadata: stripSystemMetadata(metadata) }),
+    ...rest,
+  };
+
+  // lineWidth: 0 disables wrapping (long instruction lines stay intact);
+  // blockQuote: "literal" renders multi-line strings as readable `|` blocks.
+  return stringifyYaml(doc, { lineWidth: 0, blockQuote: "literal" });
+}
+
+// metadata.version (version id, previous-version pointer, tag) is written by
+// the server on every mutation; round-tripping it through an edit would be
+// misleading at best. Everything else — including id — is user-meaningful.
+function stripSystemMetadata(
+  metadata: Record<string, unknown>,
+): Record<string, unknown> {
+  const { version, ...rest } = metadata;
+  void version;
+  return rest;
+}
+
+function isPlainObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/src/session.ts

@@ -35,3 +35,51 @@ export function resolvedSubject(subject: string | undefined): string | null {
   }
   return subject;
 }
+
+/**
+ * `SessionSpec.metadata` key carrying embedder-supplied session context —
+ * standing, per-user context (who the caller is, their experience level,
+ * their standing instructions) that the agent runner injects into the
+ * system prompt on every turn but the conversation UI never renders
+ * (stigmer/stigmer#286).
+ *
+ * Set it at session creation via `session.create({ metadata })` or the
+ * one-call bootstrap's `sessionSpec.metadata`, or use the typed
+ * `sessionContext` field on the `@stigmer/react` hooks, which maps onto
+ * this key via {@link mergeSessionContext}.
+ *
+ * Personalization, not authorization: anyone who can create the session
+ * can set this value (the same trust level as authoring the first
+ * message), so agents treat it as context — never as a credential or a
+ * permission grant. It is hidden from the conversation thread, not from
+ * the API: `session.get` returns the full spec including this key, so it
+ * is not a secrets channel — secrets belong in `runtimeEnv` or
+ * Environment resources.
+ *
+ * Pinned verbatim to `SESSION_CONTEXT_METADATA_KEY` in the runner
+ * (`backend/services/runner/src/shared/session-context.ts`), with mirror
+ * guard tests on both sides — a drift degrades to the agent simply not
+ * receiving the context, never worse.
+ */
+export const SESSION_CONTEXT_METADATA_KEY = "stigmer.ai/session-context";
+
+/**
+ * Fold a typed session-context value into a session's spec metadata map,
+ * under {@link SESSION_CONTEXT_METADATA_KEY}.
+ *
+ * The single owner of the precedence rule: a non-blank `sessionContext`
+ * wins over any value already present under the reserved key in
+ * `metadata`. A blank/undefined `sessionContext` leaves `metadata`
+ * untouched (returned as-is, possibly `undefined` — callers never send
+ * an empty map).
+ */
+export function mergeSessionContext(
+  metadata: Record<string, string> | undefined,
+  sessionContext: string | undefined,
+): Record<string, string> | undefined {
+  const context = sessionContext?.trim();
+  if (!context) {
+    return metadata;
+  }
+  return { ...metadata, [SESSION_CONTEXT_METADATA_KEY]: context };
+}

package/src/stigmer.ts

@@ -1,7 +1,9 @@
 import { ActivityClient } from "./activity.js";
 import { BillingClient } from "./billing.js";
+import { CursorAccountsClient } from "./cursor-accounts.js";
 import { GeneratedClient } from "./gen/client.js";
 import { GitHubClient } from "./github.js";
+import { ManifestClient } from "./manifest/index.js";
 import { PlatformClient } from "./platform.js";
 import { SearchClient } from "./search.js";
 import { createStigmerTransport } from "./transport.js";
@@ -27,6 +29,7 @@ type ExecutionTargetOption = StigmerConfig["executionTarget"];
  * - {@link billing} credit management and Stripe integration client
  * - Cross-resource {@link search} client
  * - {@link github} OAuth integration client
+ * - Kind-agnostic {@link manifest} client for declarative YAML apply
  *
  * @example
  * ```typescript
@@ -73,9 +76,12 @@ export class Stigmer extends GeneratedClient {
 
   readonly activity: ActivityClient;
   readonly billing: BillingClient;
+  /** Managed Cursor accounts (platform operators only). */
+  readonly cursorAccounts: CursorAccountsClient;
   readonly platform: PlatformClient;
   readonly search: SearchClient;
   readonly github: GitHubClient;
+  readonly manifest: ManifestClient;
 
   private readonly _tokenProvider: TokenProvider;
 
@@ -94,9 +100,11 @@ export class Stigmer extends GeneratedClient {
 
     this.activity = new ActivityClient(transport);
     this.billing = new BillingClient(transport);
+    this.cursorAccounts = new CursorAccountsClient(transport);
     this.platform = new PlatformClient(transport);
     this.search = new SearchClient(transport);
     this.github = new GitHubClient(transport);
+    this.manifest = new ManifestClient(transport);
 
     if (this.defaultExecutionTarget != null) {
       this._applyExecutionTargetDefaults();

package/stigmer.d.ts

@@ -1,7 +1,9 @@
 import { ActivityClient } from "./activity.js";
 import { BillingClient } from "./billing.js";
+import { CursorAccountsClient } from "./cursor-accounts.js";
 import { GeneratedClient } from "./gen/client.js";
 import { GitHubClient } from "./github.js";
+import { ManifestClient } from "./manifest/index.js";
 import { PlatformClient } from "./platform.js";
 import { SearchClient } from "./search.js";
 import { type StigmerConfig } from "./config.js";
@@ -19,6 +21,7 @@ import { ExecutionTarget } from "@stigmer/protos/ai/stigmer/agentic/session/v1/e
  * - {@link billing} credit management and Stripe integration client
  * - Cross-resource {@link search} client
  * - {@link github} OAuth integration client
+ * - Kind-agnostic {@link manifest} client for declarative YAML apply
  *
  * @example
  * ```typescript
@@ -62,9 +65,12 @@ export declare class Stigmer extends GeneratedClient {
     readonly defaultExecutionTarget: ExecutionTarget | undefined;
     readonly activity: ActivityClient;
     readonly billing: BillingClient;
+    /** Managed Cursor accounts (platform operators only). */
+    readonly cursorAccounts: CursorAccountsClient;
     readonly platform: PlatformClient;
     readonly search: SearchClient;
     readonly github: GitHubClient;
+    readonly manifest: ManifestClient;
     private readonly _tokenProvider;
     constructor(config: StigmerConfig);
     /**