@ddwang/magnitude-core 0.3.1-ddwang.6 → 0.3.1-ddwang.7

package/dist/agent/index.js

@@ -325,7 +325,12 @@ export class Agent {
             ...(this.options.prompt ? [this.options.prompt] : []),
             ...(options.prompt ? [options.prompt] : []),
         ].join('\n');
-        const taskMemory = options.memory ?? new AgentMemory({ ...this.memoryOptions, instructions: instructions === '' ? undefined : instructions });
+        const taskMemory = options.memory ?? new AgentMemory();
+        taskMemory.configure({
+            ...this.memoryOptions,
+            // Current prompts replace checkpoint instructions; omitted prompts preserve them.
+            ...(this.options.prompt != null || options.prompt !== undefined ? { instructions: instructions || null } : {}),
+        });
         if (Array.isArray(taskOrSteps)) {
             const steps = taskOrSteps;
             //this.events.emit('actStarted', steps.join(', '));

package/dist/index.cjs

@@ -1555,6 +1555,15 @@ class AgentMemory {
   get instructions() {
     return this.options.instructions;
   }
+  /** Apply current instructions and provider caching policy without replacing task evidence. */
+  configure(options) {
+    if (options.instructions !== void 0 && options.instructions !== this.options.instructions || options.promptCaching !== void 0 && options.promptCaching !== this.options.promptCaching) {
+      this.freezeMask = void 0;
+      this.cacheControlIndices = [];
+    }
+    if (options.instructions !== void 0) this.options.instructions = options.instructions;
+    if (options.promptCaching !== void 0) this.options.promptCaching = options.promptCaching;
+  }
   async render(options) {
     if (options?.history === "full") {
       const messages2 = [];
@@ -1657,14 +1666,16 @@ class AgentMemory {
     }
     const notes = this.notebook.toJSON();
     return {
-      // TODO: include other options as well
-      ...this.options.instructions ? { instructions: this.options.instructions } : {},
+      ...this.options.instructions !== null ? { instructions: this.options.instructions } : {},
       ...notes.length ? { notes } : {},
       observations
     };
   }
-  // TODO: turn into class static method / rework cons
+  /** Replace saved state atomically; runtime caching and thought limits stay with this instance. */
   async loadJSON(data) {
+    if (data.instructions !== void 0 && typeof data.instructions !== "string") {
+      throw new Error("Checkpoint instructions must be a string");
+    }
     const observations = [];
     for (const observation of data.observations) {
       observations.push(new Observation(
@@ -1677,6 +1688,7 @@ class AgentMemory {
     }
     const notebook = new TaskNotebook();
     for (const note of data.notes ?? []) notebook.put(note, (id) => this.resolveNoteSource(observations, id));
+    this.options.instructions = data.instructions ?? null;
     this.observations = observations;
     this.notebook = notebook;
     this.visibleSourceIds.clear();
@@ -4261,7 +4273,12 @@ class Agent {
       ...this.options.prompt ? [this.options.prompt] : [],
       ...options.prompt ? [options.prompt] : []
     ].join("\n");
-    const taskMemory = options.memory ?? new AgentMemory({ ...this.memoryOptions, instructions: instructions === "" ? void 0 : instructions });
+    const taskMemory = options.memory ?? new AgentMemory();
+    taskMemory.configure({
+      ...this.memoryOptions,
+      // Current prompts replace checkpoint instructions; omitted prompts preserve them.
+      ...this.options.prompt != null || options.prompt !== void 0 ? { instructions: instructions || null } : {}
+    });
     if (Array.isArray(taskOrSteps)) {
       const steps = taskOrSteps;
       await traceAsync("multistep", async (steps2, options2) => {

package/dist/index.d.cts

@@ -455,6 +455,8 @@ declare class AgentMemory {
     private cacheControlIndices;
     constructor(options?: AgentMemoryOptions);
     get instructions(): string | null;
+    /** Apply current instructions and provider caching policy without replacing task evidence. */
+    configure(options: Pick<AgentMemoryOptions, 'instructions' | 'promptCaching'>): void;
     render(options?: MemoryRenderOptions): Promise<MultiMediaMessage[]>;
     simpleRender(): Promise<(Image$1 | string)[]>;
     private observationPrefix;
@@ -466,6 +468,7 @@ declare class AgentMemory {
     recordObservation(obs: Observation): void;
     getLastThoughtMessage(): string | null;
     toJSON(): Promise<SerializedAgentMemory>;
+    /** Replace saved state atomically; runtime caching and thought limits stay with this instance. */
     loadJSON(data: SerializedAgentMemory): Promise<void>;
 }
 

package/dist/index.mjs

@@ -1532,6 +1532,15 @@ class AgentMemory {
   get instructions() {
     return this.options.instructions;
   }
+  /** Apply current instructions and provider caching policy without replacing task evidence. */
+  configure(options) {
+    if (options.instructions !== void 0 && options.instructions !== this.options.instructions || options.promptCaching !== void 0 && options.promptCaching !== this.options.promptCaching) {
+      this.freezeMask = void 0;
+      this.cacheControlIndices = [];
+    }
+    if (options.instructions !== void 0) this.options.instructions = options.instructions;
+    if (options.promptCaching !== void 0) this.options.promptCaching = options.promptCaching;
+  }
   async render(options) {
     if (options?.history === "full") {
       const messages2 = [];
@@ -1634,14 +1643,16 @@ class AgentMemory {
     }
     const notes = this.notebook.toJSON();
     return {
-      // TODO: include other options as well
-      ...this.options.instructions ? { instructions: this.options.instructions } : {},
+      ...this.options.instructions !== null ? { instructions: this.options.instructions } : {},
       ...notes.length ? { notes } : {},
       observations
     };
   }
-  // TODO: turn into class static method / rework cons
+  /** Replace saved state atomically; runtime caching and thought limits stay with this instance. */
   async loadJSON(data) {
+    if (data.instructions !== void 0 && typeof data.instructions !== "string") {
+      throw new Error("Checkpoint instructions must be a string");
+    }
     const observations = [];
     for (const observation of data.observations) {
       observations.push(new Observation(
@@ -1654,6 +1665,7 @@ class AgentMemory {
     }
     const notebook = new TaskNotebook();
     for (const note of data.notes ?? []) notebook.put(note, (id) => this.resolveNoteSource(observations, id));
+    this.options.instructions = data.instructions ?? null;
     this.observations = observations;
     this.notebook = notebook;
     this.visibleSourceIds.clear();
@@ -4238,7 +4250,12 @@ class Agent {
       ...this.options.prompt ? [this.options.prompt] : [],
       ...options.prompt ? [options.prompt] : []
     ].join("\n");
-    const taskMemory = options.memory ?? new AgentMemory({ ...this.memoryOptions, instructions: instructions === "" ? void 0 : instructions });
+    const taskMemory = options.memory ?? new AgentMemory();
+    taskMemory.configure({
+      ...this.memoryOptions,
+      // Current prompts replace checkpoint instructions; omitted prompts preserve them.
+      ...this.options.prompt != null || options.prompt !== void 0 ? { instructions: instructions || null } : {}
+    });
     if (Array.isArray(taskOrSteps)) {
       const steps = taskOrSteps;
       await traceAsync("multistep", async (steps2, options2) => {

package/dist/memory/agentMemory.d.ts

@@ -32,6 +32,8 @@ export declare class AgentMemory {
     private cacheControlIndices;
     constructor(options?: AgentMemoryOptions);
     get instructions(): string | null;
+    /** Apply current instructions and provider caching policy without replacing task evidence. */
+    configure(options: Pick<AgentMemoryOptions, 'instructions' | 'promptCaching'>): void;
     render(options?: MemoryRenderOptions): Promise<MultiMediaMessage[]>;
     simpleRender(): Promise<(BamlImage | string)[]>;
     private observationPrefix;
@@ -43,5 +45,6 @@ export declare class AgentMemory {
     recordObservation(obs: Observation): void;
     getLastThoughtMessage(): string | null;
     toJSON(): Promise<SerializedAgentMemory>;
+    /** Replace saved state atomically; runtime caching and thought limits stay with this instance. */
     loadJSON(data: SerializedAgentMemory): Promise<void>;
 }

package/dist/memory/agentMemory.js

@@ -32,6 +32,18 @@ export class AgentMemory {
         // why is this on memory? prob should just be on agent
         return this.options.instructions;
     }
+    /** Apply current instructions and provider caching policy without replacing task evidence. */
+    configure(options) {
+        if ((options.instructions !== undefined && options.instructions !== this.options.instructions)
+            || (options.promptCaching !== undefined && options.promptCaching !== this.options.promptCaching)) {
+            this.freezeMask = undefined;
+            this.cacheControlIndices = [];
+        }
+        if (options.instructions !== undefined)
+            this.options.instructions = options.instructions;
+        if (options.promptCaching !== undefined)
+            this.options.promptCaching = options.promptCaching;
+    }
     async render(options) {
         if (options?.history === 'full') {
             const messages = [];
@@ -145,32 +157,28 @@ export class AgentMemory {
         }
         const notes = this.notebook.toJSON();
         return {
-            // TODO: include other options as well
-            ...(this.options.instructions ? { instructions: this.options.instructions } : {}),
+            ...(this.options.instructions !== null ? { instructions: this.options.instructions } : {}),
             ...(notes.length ? { notes } : {}),
             observations: observations
         };
     }
-    // TODO: turn into class static method / rework cons
+    /** Replace saved state atomically; runtime caching and thought limits stay with this instance. */
     async loadJSON(data) {
-        //jsonToObservableData(data);
+        if (data.instructions !== undefined && typeof data.instructions !== 'string') {
+            throw new Error('Checkpoint instructions must be a string');
+        }
         const observations = [];
         for (const observation of data.observations) {
             observations.push(new Observation(observation.source, observation.role, await jsonToObservableData(observation.data), observation.options, observation.timestamp));
         }
-        // nvm
-        //this.instructions = this.instructions;
         const notebook = new TaskNotebook();
         for (const note of data.notes ?? [])
             notebook.put(note, id => this.resolveNoteSource(observations, id));
+        this.options.instructions = data.instructions ?? null;
         this.observations = observations;
         this.notebook = notebook;
         this.visibleSourceIds.clear();
         this.freezeMask = undefined;
         this.cacheControlIndices = [];
-        // return {
-        //     ...(this.instructions ? { instructions: this.instructions } : {}),
-        //     observations: observations
-        // };
     }
 }

package/dist/memory/agentMemory.test.js

@@ -9,6 +9,66 @@ const screen = (n) => Observation.fromConnector('fixture', {
 }, { type: 'screenshot', limit: 2, dedupe: true });
 const text = async (memory) => (await memory.render()).flatMap(message => message.content)
     .filter(part => typeof part === 'string').join('');
+for (const instructions of ['Saved planner constraint', '', undefined]) {
+    for (const promptCaching of [false, true])
+        test(`checkpoint instructions round-trip with receiving runtime configuration: ${JSON.stringify(instructions)}, caching ${promptCaching}`, async () => {
+            const original = new AgentMemory({ instructions, promptCaching: !promptCaching });
+            original.recordObservation(Observation.fromConnector('fixture', 'Saved evidence'));
+            await original.render();
+            original.remember({ key: 'saved', text: 'Saved fact', sources: [0] });
+            const saved = JSON.parse(JSON.stringify(await original.toJSON()));
+            const restored = new AgentMemory({ instructions: 'Previous task instructions', promptCaching });
+            await restored.loadJSON(saved);
+            expect(restored.instructions).toBe(instructions ?? null);
+            expect(await restored.toJSON()).toEqual(saved);
+            expect((await restored.render()).some(message => message.cacheControl)).toBe(promptCaching);
+        });
+}
+test('changing runtime caching discards frozen retention without changing the audit', async () => {
+    const memory = new AgentMemory({ instructions: 'Original constraint', promptCaching: true });
+    memory.recordObservation(Observation.fromConnector('fixture', 'Old state', { type: 'state', limit: 1 }));
+    await memory.render();
+    memory.recordObservation(Observation.fromConnector('fixture', 'New state', { type: 'state', limit: 1 }));
+    expect(await text(memory)).toContain('Old state');
+    const saved = await memory.toJSON();
+    memory.configure({ promptCaching: false });
+    expect(await text(memory)).not.toContain('Old state');
+    expect((await memory.render()).every(message => !message.cacheControl)).toBe(true);
+    expect(await memory.toJSON()).toEqual(saved);
+    memory.configure({ promptCaching: true, instructions: 'Current constraint' });
+    expect((await memory.render()).some(message => message.cacheControl)).toBe(true);
+    memory.configure({ instructions: undefined, promptCaching: undefined });
+    expect(memory.instructions).toBe('Current constraint');
+    expect((await memory.render()).some(message => message.cacheControl)).toBe(true);
+    expect((await memory.toJSON()).observations).toEqual(saved.observations);
+});
+for (const instructions of ['Current constraint', '', null, 'Original constraint', undefined]) {
+    test(`same-policy instruction update invalidates frozen retention only when changed: ${JSON.stringify(instructions)}`, async () => {
+        const memory = new AgentMemory({ instructions: 'Original constraint', promptCaching: true });
+        memory.recordObservation(Observation.fromConnector('fixture', 'Old state', { type: 'state', limit: 1 }));
+        await memory.render();
+        await memory.render();
+        memory.remember({ key: 'saved', text: 'Retained fact', sources: [0] });
+        memory.recordObservation(Observation.fromConnector('fixture', 'New state', { type: 'state', limit: 1 }));
+        const saved = await memory.toJSON();
+        memory.configure({ instructions, promptCaching: true });
+        const changed = instructions !== undefined && instructions !== 'Original constraint';
+        const rendered = await text(memory);
+        expect(rendered.includes('Old state')).toBe(!changed);
+        expect(rendered).toContain('New state');
+        expect(rendered).toContain('Retained fact');
+        expect(memory.instructions).toBe(instructions === undefined ? 'Original constraint' : instructions);
+        const after = await memory.toJSON();
+        expect(after.observations).toEqual(saved.observations);
+        expect(after.notes).toEqual(saved.notes);
+        // Changed instructions reset the cache rotation; unchanged instructions preserve its cadence.
+        memory.recordObservation(Observation.fromConnector('fixture', 'Newest state', { type: 'state', limit: 1 }));
+        const next = await memory.render();
+        expect(JSON.stringify(next).includes('New state')).toBe(changed);
+        expect(JSON.stringify(next)).toContain('Newest state');
+        expect(next.some(message => message.cacheControl)).toBe(true);
+    });
+}
 for (const promptCaching of [false, true])
     test(`current observations replace cached state without changing history or audit, caching ${promptCaching}`, async () => {
         const memory = new AgentMemory({ promptCaching });
@@ -142,11 +202,14 @@ test('loading legacy memory clears notes and visibility/cache state', async () =
     expect(await text(memory)).toContain('New task observation');
 });
 test('malformed checkpoint provenance does not replace current memory', async () => {
-    const memory = new AgentMemory();
+    const memory = new AgentMemory({ instructions: 'Keep these instructions', promptCaching: true });
     memory.recordObservation(screen(0));
     const saved = await memory.toJSON();
-    await expect(memory.loadJSON({ ...saved, notes: [{ key: 'bad', text: 'claim', sources: [50] }] })).rejects.toThrow();
+    await expect(memory.loadJSON({ ...saved, instructions: 42 })).rejects.toThrow('instructions must be a string');
+    expect(await memory.toJSON()).toEqual(saved);
+    await expect(memory.loadJSON({ ...saved, instructions: 'Rejected instructions', notes: [{ key: 'bad', text: 'claim', sources: [50] }] })).rejects.toThrow();
     expect(await memory.toJSON()).toEqual(saved);
+    expect((await memory.render()).some(message => message.cacheControl)).toBe(true);
 });
 for (const promptCaching of [false, true])
     test(`completed checks outlive the default thought window and can be corrected, caching ${promptCaching}`, async () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ddwang/magnitude-core",
-  "version": "0.3.1-ddwang.6",
+  "version": "0.3.1-ddwang.7",
   "description": "Magnitude e2e testing agent",
   "publishConfig": {
     "access": "public"