CCR 3

Type the handle's metadata as deeply readonly.

`defineFactory` deep-freezes the snapshot it stores, but `FactoryHandle.meta`
was typed as a mutable `FactoryMeta`, so `handle.meta.name = "..."` and
`handle.meta.phases.push(...)` compiled and then threw at runtime. The test
asserts both halves: the mutation is a type error and it also throws.

Author: MRayermannMSFT

nodejs/src/factory.ts

@@ -194,11 +194,24 @@ export interface FactoryDefinition<
  * @experimental Part of the experimental Agent Factories surface and may
  * change or be removed in future SDK or CLI releases.
  */
+/**
+ * A deeply immutable view of a value.
+ *
+ * `defineFactory` deep-freezes the metadata it stores, so the handle's view of
+ * it has to be readonly all the way down or `handle.meta.name = "..."` and
+ * `handle.meta.phases.push(...)` would compile and then throw at runtime.
+ */
+type DeepReadonly<T> = T extends (infer U)[]
+    ? readonly DeepReadonly<U>[]
+    : T extends object
+      ? { readonly [K in keyof T]: DeepReadonly<T[K]> }
+      : T;
+
 export interface FactoryHandle<
     TArgs extends JsonValue = JsonValue,
     TResult extends JsonValue | void = JsonValue | void,
 > {
-    readonly meta: FactoryMeta;
+    readonly meta: DeepReadonly<FactoryMeta>;
     readonly [factoryHandleBrand]: {
         readonly args: TArgs;
         readonly result: TResult;
@@ -422,7 +435,7 @@ export function defineFactory<
         meta,
         run: definition.run,
     };
-    const handle = Object.freeze({ meta }) as FactoryHandle<TArgs, TResult>;
+    const handle = Object.freeze({ meta }) as unknown as FactoryHandle<TArgs, TResult>;
 
     factoryHandles.set(handle, stored);
     return handle;

nodejs/test/factory.test.ts

@@ -69,6 +69,18 @@ describe("factories", () => {
         meta.name = "no-limits";
         meta.phases.length = 0;
 
+        // The stored metadata is deep-frozen, so the handle's view of it must be
+        // readonly all the way down. Assert both halves: the mutation is a type
+        // error, and it also throws at runtime.
+        expect(() => {
+            // @ts-expect-error handle.meta is deeply readonly.
+            handle.meta.name = "mutated";
+        }).toThrow(TypeError);
+        expect(() => {
+            // @ts-expect-error handle.meta.phases is a readonly array.
+            handle.meta.phases.push({ title: "late" });
+        }).toThrow(TypeError);
+
         const session = new CopilotSession("session-1", {} as never);
         session.registerFactories([handle]);
         const result = await session.clientSessionApis.factory!.execute({