@stigmer/sdk 3.2.3 → 3.4.0

package/manifest/serialize.d.ts

@@ -0,0 +1,24 @@
+import { type Message } from "@bufbuild/protobuf";
+/**
+ * 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 declare function serializeManifest(message: Message): string;
+//# sourceMappingURL=serialize.d.ts.map

package/manifest/serialize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.d.ts","sourceRoot":"","sources":["../../src/manifest/serialize.ts"],"names":[],"mappings":"AAeA,OAAO,EAAU,KAAK,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAI1D;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAoC1D"}

package/manifest/serialize.js

@@ -0,0 +1,78 @@
+// 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 } 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) {
+    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;
+    void status;
+    const doc = {
+        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) {
+    const { version, ...rest } = metadata;
+    void version;
+    return rest;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=serialize.js.map

package/manifest/serialize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialize.js","sourceRoot":"","sources":["../../src/manifest/serialize.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,sEAAsE;AACtE,yDAAyD;AACzD,yEAAyE;AACzE,uEAAuE;AACvE,2BAA2B;AAC3B,EAAE;AACF,wEAAwE;AACxE,oCAAoC;AACpC,6EAA6E;AAC7E,mDAAmD;AACnD,6EAA6E;AAC7E,uEAAuE;AAEvE,OAAO,EAAE,MAAM,EAAgB,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,SAAS,IAAI,aAAa,EAAE,MAAM,MAAM,CAAC;AAClD,OAAO,EAAE,0BAA0B,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAE1E;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAgB;IAChD,MAAM,OAAO,GAAG,0BAA0B,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAC9D,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC1B,MAAM,SAAS,GAAG,aAAa,EAAE;aAC9B,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;aACtB,IAAI,CAAC,IAAI,CAAC,CAAC;QACd,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,CAAC,SAAS,8BAA8B;YACjE,8CAA8C,SAAS,GAAG,CAC7D,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,EAAE,iBAAiB,EAAE,IAAI,EAAE,CAAC,CAAC;IAC1E,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,CAAC;QACrE,MAAM,IAAI,KAAK,CACb,oBAAoB,OAAO,CAAC,WAAW,0BAA0B;YAC/D,uBAAuB,CAC1B,CAAC;IACJ,CAAC;IAED,MAAM,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,EAAE,GACpD,IAA+B,CAAC;IAClC,KAAK,MAAM,CAAC;IAEZ,MAAM,GAAG,GAA4B;QACnC,UAAU,EAAE,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,EAAE;YAC/D,CAAC,CAAC,WAAW;YACb,CAAC,CAAC,OAAO,CAAC,UAAU;QACtB,IAAI,EAAE,OAAO,IAAI,KAAK,QAAQ,IAAI,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ;QACvE,GAAG,CAAC,aAAa,CAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,mBAAmB,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC3E,GAAG,IAAI;KACR,CAAC;IAEF,uEAAuE;IACvE,2EAA2E;IAC3E,OAAO,aAAa,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,CAAC,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;AACrE,CAAC;AAED,6EAA6E;AAC7E,2EAA2E;AAC3E,2EAA2E;AAC3E,SAAS,mBAAmB,CAC1B,QAAiC;IAEjC,MAAM,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,QAAQ,CAAC;IACtC,KAAK,OAAO,CAAC;IACb,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,aAAa,CAAC,KAAc;IACnC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stigmer/sdk",
-  "version": "3.2.3",
+  "version": "3.4.0",
   "description": "Stigmer TypeScript SDK — typed API client for all Stigmer platform resources",
   "license": "Apache-2.0",
   "type": "module",
@@ -39,11 +39,12 @@
   },
   "dependencies": {
     "@connectrpc/connect": "^2.0.0",
-    "@connectrpc/connect-web": "^2.0.0"
+    "@connectrpc/connect-web": "^2.0.0",
+    "yaml": "^2.8.2"
   },
   "peerDependencies": {
     "@bufbuild/protobuf": "^2.0.0",
     "@connectrpc/connect-node": "^2.0.0",
-    "@stigmer/protos": "3.2.3"
+    "@stigmer/protos": "3.4.0"
   }
 }

package/session.d.ts

@@ -28,4 +28,41 @@ export declare const PENDING_SUBJECT = "Auto-created session";
  * `client-apps/cli/internal/cli/session/get.go`.
  */
 export declare function resolvedSubject(subject: string | undefined): string | null;
+/**
+ * `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 declare 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 declare function mergeSessionContext(metadata: Record<string, string> | undefined, sessionContext: string | undefined): Record<string, string> | undefined;
 //# sourceMappingURL=session.d.ts.map

package/session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,yBAAyB,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAK1E"}
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,yBAAyB,CAAC;AAEtD;;;;;;;;;GASG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAK1E;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,4BAA4B,+BAA+B,CAAC;AAEzE;;;;;;;;;GASG;AACH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,EAC5C,cAAc,EAAE,MAAM,GAAG,SAAS,GACjC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,SAAS,CAMpC"}

package/session.js

@@ -33,4 +33,47 @@ export function resolvedSubject(subject) {
     }
     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, sessionContext) {
+    const context = sessionContext?.trim();
+    if (!context) {
+        return metadata;
+    }
+    return { ...metadata, [SESSION_CONTEXT_METADATA_KEY]: context };
+}
 //# sourceMappingURL=session.js.map

package/session.js.map

@@ -1 +1 @@
-{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,sBAAsB,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAA2B;IACzD,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,eAAe,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}
+{"version":3,"file":"session.js","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,sBAAsB,CAAC;AAEtD;;;;;;;;;GASG;AACH,MAAM,UAAU,eAAe,CAAC,OAA2B;IACzD,IAAI,CAAC,OAAO,IAAI,OAAO,KAAK,eAAe,EAAE,CAAC;QAC5C,OAAO,IAAI,CAAC;IACd,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,MAAM,CAAC,MAAM,4BAA4B,GAAG,4BAA4B,CAAC;AAEzE;;;;;;;;;GASG;AACH,MAAM,UAAU,mBAAmB,CACjC,QAA4C,EAC5C,cAAkC;IAElC,MAAM,OAAO,GAAG,cAAc,EAAE,IAAI,EAAE,CAAC;IACvC,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,QAAQ,CAAC;IAClB,CAAC;IACD,OAAO,EAAE,GAAG,QAAQ,EAAE,CAAC,4BAA4B,CAAC,EAAE,OAAO,EAAE,CAAC;AAClE,CAAC"}

package/src/__tests__/errors.test.ts

@@ -8,6 +8,7 @@ import {
   isTransientStreamError,
   getUserMessage,
   getErrorReason,
+  getRecordConstraint,
   annotateRpcError,
   getRpcMetadata,
   type ErrorCategory,
@@ -328,6 +329,63 @@ describe("getErrorReason", () => {
   });
 });
 
+describe("getRecordConstraint", () => {
+  const recordViolation = (metadata: Record<string, string>) =>
+    new ConnectError("that slot is already booked", Code.AlreadyExists, undefined, [
+      {
+        desc: ErrorInfoSchema,
+        value: {
+          domain: "datastore.stigmer.ai",
+          reason: "CONSTRAINT_VIOLATION",
+          metadata,
+        },
+      },
+    ]);
+
+  it("extracts the constraint name from a record-RPC violation", () => {
+    expect(getRecordConstraint(recordViolation({ constraint: "one_confirmed_per_slot" })))
+      .toBe("one_confirmed_per_slot");
+  });
+
+  it("walks the cause chain of an SDK-wrapped StigmerError", () => {
+    const connectError = recordViolation({ constraint: "one_confirmed_per_slot" });
+    const wrapped = new StigmerError(
+      "already-exists",
+      connectError.rawMessage,
+      Code.AlreadyExists,
+      { cause: connectError },
+    );
+    expect(getRecordConstraint(wrapped)).toBe("one_confirmed_per_slot");
+  });
+
+  it("returns null when the ErrorInfo domain is not the records domain", () => {
+    const foreign = new ConnectError("workspace taken", Code.FailedPrecondition, undefined, [
+      {
+        desc: ErrorInfoSchema,
+        value: {
+          domain: "stigmer.ai",
+          reason: "SLACK_WORKSPACE_ALREADY_CONNECTED",
+          metadata: { constraint: "should_not_leak" },
+        },
+      },
+    ]);
+    expect(getRecordConstraint(foreign)).toBeNull();
+  });
+
+  it("returns null when the violation carries no constraint metadata", () => {
+    expect(getRecordConstraint(recordViolation({}))).toBeNull();
+    expect(getRecordConstraint(recordViolation({ constraint: "" }))).toBeNull();
+  });
+
+  it("returns null for errors without ErrorInfo", () => {
+    expect(
+      getRecordConstraint(new ConnectError("bare", Code.AlreadyExists)),
+    ).toBeNull();
+    expect(getRecordConstraint(new Error("plain"))).toBeNull();
+    expect(getRecordConstraint(null)).toBeNull();
+  });
+});
+
 describe("annotateRpcError / getRpcMetadata", () => {
   it("roundtrips metadata on an error object", () => {
     const err = new Error("test");

package/src/__tests__/manifest.test.ts

@@ -0,0 +1,271 @@
+import { describe, it, expect } from "vitest";
+import { create, equals } from "@bufbuild/protobuf";
+import { AgentSchema, type Agent } from "@stigmer/protos/ai/stigmer/agentic/agent/v1/api_pb";
+import { EnvironmentSchema, type Environment } from "@stigmer/protos/ai/stigmer/agentic/environment/v1/api_pb";
+import { ApiResourceMetadataSchema } from "@stigmer/protos/ai/stigmer/commons/apiresource/metadata_pb";
+import { parse as parseYaml } from "yaml";
+import { parseManifest } from "../manifest/parse";
+import { serializeManifest } from "../manifest/serialize";
+import { manifestKinds, manifestHandlerForYamlKind } from "../manifest/registry";
+
+/**
+ * Manifest engine contract tests.
+ *
+ * The engine's core promise is *round-trip fidelity against the generated
+ * proto schemas*: any resource the server returns serializes to YAML that
+ * parses back to the same proto (minus system-managed state), and any
+ * repo-authored manifest (snake_case fields, `apiVersion` spelling) parses
+ * to a proto the `apply` RPC accepts. Fixtures mirror the real manifests
+ * in the whatsapp-doctor-assistant dogfooding repo.
+ */
+
+// ---------------------------------------------------------------------------
+// Fixtures — shaped like the whatsapp-doctor-assistant repo manifests
+// ---------------------------------------------------------------------------
+
+const AGENT_YAML = `
+apiVersion: agentic.stigmer.ai/v1
+kind: Agent
+metadata:
+  name: clinic-patient-assistant
+  org: rakeshreddi098
+spec:
+  description: Patient-facing WhatsApp assistant for the clinic.
+  instructions: |
+    You are the appointment assistant for the clinic.
+    Short messages. One question at a time.
+`;
+
+const ENVIRONMENT_YAML = `
+apiVersion: agentic.stigmer.ai/v1
+kind: Environment
+metadata:
+  name: clinic-patient-db
+  org: rakeshreddi098
+spec:
+  description: "Clinic records access for the patient assistant"
+  data:
+    POSTGRES_CONNECTION_URL:
+      value: "postgresql://patient_role:secret@host:5432/postgres"
+      is_secret: true
+      description: "Supabase Postgres connection URL for patient_role"
+`;
+
+const AGENT_CHANNEL_YAML = `
+apiVersion: agentic.stigmer.ai/v1
+kind: AgentChannel
+metadata:
+  name: clinic-patient-whatsapp
+  org: rakeshreddi098
+spec:
+  agent_ref:
+    kind: agent
+    org: rakeshreddi098
+    slug: clinic-patient-assistant
+  enabled: true
+  whatsapp:
+    phone_number_id: "1234567890"
+  app_ref:
+    kind: channel_app
+    org: rakeshreddi098
+    slug: hosipital
+  environment_refs:
+    - kind: environment
+      org: rakeshreddi098
+      slug: clinic-patient-db
+`;
+
+// ---------------------------------------------------------------------------
+// parseManifest
+// ---------------------------------------------------------------------------
+
+describe("parseManifest", () => {
+  it("parses a snake_case Agent manifest into a full Agent proto", () => {
+    const docs = parseManifest(AGENT_YAML);
+    expect(docs).toHaveLength(1);
+
+    const doc = docs[0];
+    expect(doc.handler.yamlKind).toBe("Agent");
+    expect(doc.name).toBe("clinic-patient-assistant");
+    expect(doc.org).toBe("rakeshreddi098");
+
+    const agent = doc.message as Agent;
+    expect(agent.spec?.description).toBe(
+      "Patient-facing WhatsApp assistant for the clinic.",
+    );
+    expect(agent.spec?.instructions).toContain("appointment assistant");
+  });
+
+  it("parses an AgentChannel manifest with enum-valued resource refs", () => {
+    const docs = parseManifest(AGENT_CHANNEL_YAML);
+    expect(docs).toHaveLength(1);
+    expect(docs[0].handler.yamlKind).toBe("AgentChannel");
+    expect(docs[0].slug).toBe("clinic-patient-whatsapp");
+  });
+
+  it("sorts multi-document manifests into dependency apply order", () => {
+    // Authored channel-first; the Environment must still apply first.
+    const docs = parseManifest(`${AGENT_CHANNEL_YAML}\n---\n${ENVIRONMENT_YAML}`);
+    expect(docs.map((d) => d.handler.yamlKind)).toEqual([
+      "Environment",
+      "AgentChannel",
+    ]);
+  });
+
+  it("injects the target org when the document omits it", () => {
+    const yaml = AGENT_YAML.replace("  org: rakeshreddi098\n", "");
+    const docs = parseManifest(yaml, { org: "acme" });
+    expect(docs[0].org).toBe("acme");
+    expect(docs[0].warning).toBeUndefined();
+  });
+
+  it("honors the document org and warns when it differs from the target", () => {
+    const docs = parseManifest(AGENT_YAML, { org: "acme" });
+    expect(docs[0].org).toBe("rakeshreddi098");
+    expect(docs[0].warning).toContain('"rakeshreddi098"');
+    expect(docs[0].warning).toContain('"acme"');
+  });
+
+  it("rejects unknown fields loudly (strict schema contract)", () => {
+    const yaml = AGENT_YAML.replace("spec:", "spec:\n  instrctions: typo");
+    expect(() => parseManifest(yaml)).toThrow(/Invalid Agent/);
+  });
+
+  it("rejects a document without a kind", () => {
+    expect(() => parseManifest("metadata:\n  name: x\n")).toThrow(/'kind'/);
+  });
+
+  it("rejects unsupported kinds with the supported list", () => {
+    expect(() => parseManifest("kind: Skill\nmetadata:\n  name: x\n")).toThrow(
+      /Unsupported resource kind "Skill".*Agent/s,
+    );
+  });
+
+  it("rejects empty input with actionable guidance", () => {
+    expect(() => parseManifest("   \n")).toThrow(/empty/i);
+  });
+
+  it("rejects malformed YAML", () => {
+    expect(() => parseManifest("kind: Agent\n  bad indent: [")).toThrow(
+      /Invalid YAML/,
+    );
+  });
+});
+
+// ---------------------------------------------------------------------------
+// serializeManifest
+// ---------------------------------------------------------------------------
+
+describe("serializeManifest", () => {
+  const agent = create(AgentSchema, {
+    apiVersion: "agentic.stigmer.ai/v1",
+    kind: "Agent",
+    metadata: {
+      id: "agt_01example",
+      name: "clinic-patient-assistant",
+      slug: "clinic-patient-assistant",
+      org: "rakeshreddi098",
+      version: { id: "ver_01", message: "server-managed" },
+    },
+    spec: {
+      description: "Patient-facing WhatsApp assistant.",
+      instructions: "Short messages.\nOne question at a time.\n",
+    },
+    status: { defaultInstanceId: "agi_01example" },
+  });
+
+  it("emits the canonical envelope: apiVersion spelling, no status", () => {
+    const yaml = serializeManifest(agent);
+    const doc = parseYaml(yaml) as Record<string, unknown>;
+
+    expect(Object.keys(doc)[0]).toBe("apiVersion");
+    expect(doc.apiVersion).toBe("agentic.stigmer.ai/v1");
+    expect(doc.kind).toBe("Agent");
+    expect(doc.status).toBeUndefined();
+    expect(yaml).not.toContain("api_version:");
+  });
+
+  it("keeps metadata.id but strips server-managed metadata.version", () => {
+    const doc = parseYaml(serializeManifest(agent)) as {
+      metadata: Record<string, unknown>;
+    };
+    expect(doc.metadata.id).toBe("agt_01example");
+    expect(doc.metadata.version).toBeUndefined();
+  });
+
+  it("fills apiVersion and kind from the registry when the proto omits them", () => {
+    const bare = create(AgentSchema, {
+      metadata: { name: "x", org: "acme" },
+    });
+    const doc = parseYaml(serializeManifest(bare)) as Record<string, unknown>;
+    expect(doc.apiVersion).toBe("agentic.stigmer.ai/v1");
+    expect(doc.kind).toBe("Agent");
+  });
+
+  it("round-trips through parseManifest to an equal proto", () => {
+    const docs = parseManifest(serializeManifest(agent));
+    expect(docs).toHaveLength(1);
+
+    // The round-tripped proto matches the original minus system-managed
+    // state (status, metadata.version) — exactly what apply consumes.
+    const expected = create(AgentSchema, {
+      ...agent,
+      status: undefined,
+      metadata: { ...agent.metadata!, version: undefined },
+    });
+    expect(equals(AgentSchema, docs[0].message as Agent, expected)).toBe(true);
+  });
+
+  it("round-trips Environment secret values byte-identically", () => {
+    const env = create(EnvironmentSchema, {
+      metadata: { name: "clinic-patient-db", org: "rakeshreddi098" },
+      spec: {
+        data: {
+          POSTGRES_CONNECTION_URL: {
+            value: "***REDACTED***",
+            isSecret: true,
+            description: "Supabase Postgres connection URL",
+          },
+        },
+      },
+    });
+
+    const docs = parseManifest(serializeManifest(env));
+    const roundTripped = docs[0].message as Environment;
+    expect(roundTripped.spec?.data.POSTGRES_CONNECTION_URL?.value).toBe(
+      "***REDACTED***",
+    );
+    expect(roundTripped.spec?.data.POSTGRES_CONNECTION_URL?.isSecret).toBe(true);
+  });
+
+  it("rejects messages of kinds outside the registry", () => {
+    // ApiResourceMetadata is a real proto message but not a manifest kind.
+    const notAResource = create(ApiResourceMetadataSchema, { name: "x" });
+    expect(() => serializeManifest(notAResource)).toThrow(/not.*registry/i);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Registry invariants
+// ---------------------------------------------------------------------------
+
+describe("manifest registry", () => {
+  it("every handler resolves by its own YAML kind", () => {
+    for (const handler of manifestKinds()) {
+      expect(manifestHandlerForYamlKind(handler.yamlKind)).toBe(handler);
+    }
+  });
+
+  it("apply order is strictly increasing (no accidental ties)", () => {
+    const orders = manifestKinds().map((h) => h.applyOrder);
+    for (let i = 1; i < orders.length; i++) {
+      expect(orders[i]).toBeGreaterThan(orders[i - 1]);
+    }
+  });
+
+  it("covers the kinds the console flows depend on", () => {
+    for (const kind of ["Agent", "McpServer", "Workflow", "Environment", "AgentChannel", "ChannelApp"]) {
+      expect(manifestHandlerForYamlKind(kind), `missing handler for ${kind}`).toBeDefined();
+    }
+  });
+});

package/src/__tests__/session.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Unit tests for the hand-written session utilities: the pinned
+ * session-context metadata key and the typed-context merge semantics.
+ */
+
+import { describe, it, expect } from "vitest";
+import {
+  SESSION_CONTEXT_METADATA_KEY,
+  mergeSessionContext,
+} from "../session.js";
+
+describe("SESSION_CONTEXT_METADATA_KEY", () => {
+  it("is pinned verbatim to the runner's constant (mirror guard)", () => {
+    // Pinned to SESSION_CONTEXT_METADATA_KEY in
+    // backend/services/runner/src/shared/session-context.ts. Changing
+    // either side alone silently blinds the agent to the embedder's
+    // context; change BOTH together.
+    expect(SESSION_CONTEXT_METADATA_KEY).toBe("stigmer.ai/session-context");
+  });
+});
+
+describe("mergeSessionContext", () => {
+  it("folds the context into the metadata map under the reserved key", () => {
+    expect(mergeSessionContext({ "acme/tenant": "t-1" }, "Role: admin")).toEqual({
+      "acme/tenant": "t-1",
+      [SESSION_CONTEXT_METADATA_KEY]: "Role: admin",
+    });
+  });
+
+  it("creates the map when metadata is undefined", () => {
+    expect(mergeSessionContext(undefined, "Role: admin")).toEqual({
+      [SESSION_CONTEXT_METADATA_KEY]: "Role: admin",
+    });
+  });
+
+  it("lets the typed field win over a raw entry under the reserved key", () => {
+    expect(
+      mergeSessionContext(
+        { [SESSION_CONTEXT_METADATA_KEY]: "stale raw value" },
+        "typed value",
+      ),
+    ).toEqual({ [SESSION_CONTEXT_METADATA_KEY]: "typed value" });
+  });
+
+  it("returns metadata untouched when the context is undefined", () => {
+    const metadata = { "acme/tenant": "t-1" };
+    expect(mergeSessionContext(metadata, undefined)).toBe(metadata);
+  });
+
+  it("returns undefined when both inputs are absent — callers never send an empty map", () => {
+    expect(mergeSessionContext(undefined, undefined)).toBeUndefined();
+    expect(mergeSessionContext(undefined, "   ")).toBeUndefined();
+  });
+
+  it("trims the context before storing (blank means absent)", () => {
+    expect(mergeSessionContext(undefined, "  Role: admin  ")).toEqual({
+      [SESSION_CONTEXT_METADATA_KEY]: "Role: admin",
+    });
+  });
+
+  it("does not mutate the caller's metadata map", () => {
+    const metadata = { "acme/tenant": "t-1" };
+    mergeSessionContext(metadata, "Role: admin");
+    expect(metadata).toEqual({ "acme/tenant": "t-1" });
+  });
+});