@strands-agents/sdk 1.5.0 → 1.6.0

package/dist/src/injection/__tests__/message-injection.test.js

@@ -0,0 +1,200 @@
+import { describe, it, expect, vi } from 'vitest';
+import { Message, TextBlock, ToolResultBlock } from '../../types/messages.js';
+import { foldIntoLastUserMessage, isUserTurn, resolveTrigger, createInjectionMiddleware } from '../message-injection.js';
+import { createMockAgent } from '../../__fixtures__/agent-helpers.js';
+import { logger } from '../../logging/logger.js';
+const user = (text) => new Message({ role: 'user', content: [new TextBlock(text)] });
+const assistant = (text) => new Message({ role: 'assistant', content: [new TextBlock(text)] });
+const toolResult = () => new Message({
+    role: 'user',
+    content: [new ToolResultBlock({ toolUseId: 't1', status: 'success', content: [new TextBlock('done')] })],
+});
+// resolveTrigger predicates take an InjectionContext; tests only exercise `messages`, so a minimal bag suffices.
+const injectionCtx = (messages) => ({ messages });
+describe('foldIntoLastUserMessage', () => {
+    it('prepends the text as a leading TextBlock on the last user message, ahead of its content', () => {
+        const messages = [user('original task'), assistant('prior step'), user('next ask')];
+        const result = foldIntoLastUserMessage(messages, 'INJECTED');
+        // The earlier user/assistant turns are untouched; the last user message gains a leading INJECTED
+        // block ahead of its own content, keeping the user's ask in the recency slot.
+        expect(result.map((m) => m.toJSON())).toStrictEqual([
+            { role: 'user', content: [{ text: 'original task' }] },
+            { role: 'assistant', content: [{ text: 'prior step' }] },
+            { role: 'user', content: [{ text: 'INJECTED' }, { text: 'next ask' }] },
+        ]);
+    });
+    it('returns a new array and does not mutate the input or its messages', () => {
+        const original = user('ask');
+        const messages = [assistant('prior'), original];
+        const result = foldIntoLastUserMessage(messages, 'INJECTED');
+        expect(result).not.toBe(messages);
+        expect(messages[1]).toBe(original);
+        expect(original.content).toHaveLength(1); // untouched
+        expect(result[1]).not.toBe(original);
+    });
+    it('appends after the tool result block when the target is a tool-result turn', () => {
+        const tr = toolResult();
+        const result = foldIntoLastUserMessage([user('task'), assistant('thinking'), tr], 'INJECTED');
+        // Providers require the tool result to be the first block in the turn, so the injected text is
+        // appended rather than prepended here.
+        expect(result.map((m) => m.toJSON())).toStrictEqual([
+            { role: 'user', content: [{ text: 'task' }] },
+            { role: 'assistant', content: [{ text: 'thinking' }] },
+            { role: 'user', content: [tr.toJSON().content[0], { text: 'INJECTED' }] },
+        ]);
+    });
+    it('targets the most recent user message when several exist', () => {
+        const messages = [user('first'), assistant('a'), user('second')];
+        const result = foldIntoLastUserMessage(messages, 'INJECTED');
+        expect(result.map((m) => m.toJSON())).toStrictEqual([
+            { role: 'user', content: [{ text: 'first' }] }, // earlier user untouched
+            { role: 'assistant', content: [{ text: 'a' }] },
+            { role: 'user', content: [{ text: 'INJECTED' }, { text: 'second' }] },
+        ]);
+    });
+    it('preserves message metadata on the folded message', () => {
+        const tagged = new Message({
+            role: 'user',
+            content: [new TextBlock('ask')],
+            metadata: { custom: { keep: 'me' } },
+        });
+        const result = foldIntoLastUserMessage([tagged], 'INJECTED');
+        expect(result[0].metadata?.custom).toStrictEqual({ keep: 'me' });
+    });
+    it('returns the input unchanged when there is no user message', () => {
+        const messages = [assistant('only assistant')];
+        const result = foldIntoLastUserMessage(messages, 'INJECTED');
+        expect(result).toBe(messages);
+    });
+});
+describe('isUserTurn', () => {
+    it('is true when the last message is a plain user ask', () => {
+        expect(isUserTurn([assistant('prior').toJSON(), user('ask').toJSON()])).toBe(true);
+    });
+    it('is false when the last message is a user tool-result turn', () => {
+        expect(isUserTurn([user('task').toJSON(), assistant('a').toJSON(), toolResult().toJSON()])).toBe(false);
+    });
+    it('is false when the last message is an assistant message', () => {
+        expect(isUserTurn([user('ask').toJSON(), assistant('reply').toJSON()])).toBe(false);
+    });
+    it('is false for an empty conversation', () => {
+        expect(isUserTurn([])).toBe(false);
+    });
+});
+describe('resolveTrigger', () => {
+    it('defaults (undefined) to the userTurn policy', () => {
+        const trigger = resolveTrigger(undefined);
+        expect(trigger(injectionCtx([user('ask').toJSON()]))).toBe(true);
+        expect(trigger(injectionCtx([toolResult().toJSON()]))).toBe(false);
+    });
+    it("'userTurn' uses isUserTurn", () => {
+        const trigger = resolveTrigger('userTurn');
+        expect(trigger(injectionCtx([user('ask').toJSON()]))).toBe(true);
+        expect(trigger(injectionCtx([toolResult().toJSON()]))).toBe(false);
+    });
+    it("'everyTurn' always fires", () => {
+        const trigger = resolveTrigger('everyTurn');
+        expect(trigger(injectionCtx([]))).toBe(true);
+        expect(trigger(injectionCtx([toolResult().toJSON()]))).toBe(true);
+    });
+    it('uses a custom predicate over the context', () => {
+        const trigger = resolveTrigger((context) => context.messages.length >= 2);
+        expect(trigger(injectionCtx([user('a').toJSON()]))).toBe(false);
+        expect(trigger(injectionCtx([user('a').toJSON(), assistant('b').toJSON()]))).toBe(true);
+    });
+    it('fails open (returns false, logs) when a custom predicate throws', () => {
+        const warn = vi.spyOn(logger, 'warn').mockImplementation(() => { });
+        const trigger = resolveTrigger(() => {
+            throw new Error('boom');
+        });
+        expect(trigger(injectionCtx([user('ask').toJSON()]))).toBe(false);
+        expect(warn).toHaveBeenCalled();
+        warn.mockRestore();
+    });
+});
+describe('createInjectionMiddleware', () => {
+    // The handler is an InvokeModelStage.Input transformer. It reads `context.messages` and derives the
+    // InjectionContext (appState/agent) from `context.agent`, then spreads the rest through, so a context
+    // carrying `messages` plus a mock agent exercises it faithfully.
+    const ctx = (messages) => ({ messages, agent: createMockAgent() });
+    it('folds renderContent() text into the latest user message, leaving other context fields intact', async () => {
+        const handler = createInjectionMiddleware({ renderContent: async () => 'INJECTED' });
+        const result = await handler(ctx([assistant('prior'), user('ask')]));
+        expect(result.messages.map((m) => m.toJSON())).toStrictEqual([
+            { role: 'assistant', content: [{ text: 'prior' }] },
+            { role: 'user', content: [{ text: 'INJECTED' }, { text: 'ask' }] },
+        ]);
+    });
+    it('passes an InjectionContext carrying the conversation (as data) to renderContent', async () => {
+        const seen = [];
+        const handler = createInjectionMiddleware({
+            renderContent: async (context) => {
+                seen.push(...context.messages.map((m) => m.role));
+                return 'x';
+            },
+        });
+        await handler(ctx([assistant('prior'), user('ask')]));
+        expect(seen).toStrictEqual(['assistant', 'user']);
+    });
+    it('exposes appState and the agent on the InjectionContext', async () => {
+        const appState = { get: () => 'stashed' };
+        const agent = { appState };
+        const input = { messages: [user('ask')], agent };
+        let received;
+        const handler = createInjectionMiddleware({
+            renderContent: async (context) => {
+                received = { appState: context.appState, agent: context.agent };
+                return undefined;
+            },
+        });
+        await handler(input);
+        expect(received).toStrictEqual({ appState, agent });
+    });
+    it('returns the context unchanged when the trigger does not fire', async () => {
+        const renderContent = vi.fn(async () => 'x');
+        const handler = createInjectionMiddleware({ renderContent }); // default 'userTurn'
+        const input = ctx([user('task'), assistant('a'), toolResult()]);
+        const result = await handler(input);
+        expect(result).toBe(input);
+        expect(renderContent).not.toHaveBeenCalled();
+    });
+    it("'everyTurn' injects on an autonomous tool-result turn, keeping the tool result first", async () => {
+        const handler = createInjectionMiddleware({ trigger: 'everyTurn', renderContent: async () => 'INJECTED' });
+        const tr = toolResult();
+        const result = await handler(ctx([user('task'), assistant('a'), tr]));
+        // The most recent user message on a tool-result turn carries the tool result, which must stay the
+        // first block, so the injected text is appended after it.
+        expect(result.messages.map((m) => m.toJSON())).toStrictEqual([
+            { role: 'user', content: [{ text: 'task' }] },
+            { role: 'assistant', content: [{ text: 'a' }] },
+            { role: 'user', content: [tr.toJSON().content[0], { text: 'INJECTED' }] },
+        ]);
+    });
+    it('returns the context unchanged when renderContent yields empty text', async () => {
+        const handler = createInjectionMiddleware({ renderContent: async () => '   ' });
+        const input = ctx([assistant('prior'), user('ask')]);
+        const result = await handler(input);
+        expect(result).toBe(input);
+    });
+    it('fails open (returns the context unchanged, logs) when renderContent throws', async () => {
+        const warn = vi.spyOn(logger, 'warn').mockImplementation(() => { });
+        const handler = createInjectionMiddleware({
+            renderContent: async () => {
+                throw new Error('boom');
+            },
+        });
+        const input = ctx([assistant('prior'), user('ask')]);
+        const result = await handler(input);
+        expect(result).toBe(input);
+        expect(warn).toHaveBeenCalled();
+        warn.mockRestore();
+    });
+    it('does not mutate the original context messages', async () => {
+        const handler = createInjectionMiddleware({ renderContent: async () => 'INJECTED' });
+        const input = ctx([assistant('prior'), user('ask')]);
+        const before = input.messages[1];
+        await handler(input);
+        expect(before.content).toHaveLength(1); // the original user message is untouched
+    });
+});
+//# sourceMappingURL=message-injection.test.js.map

package/dist/src/injection/__tests__/message-injection.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-injection.test.js","sourceRoot":"","sources":["../../../../src/injection/__tests__/message-injection.test.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,QAAQ,CAAA;AACjD,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAA;AAE7E,OAAO,EAAE,uBAAuB,EAAE,UAAU,EAAE,cAAc,EAAE,yBAAyB,EAAE,MAAM,yBAAyB,CAAA;AAGxH,OAAO,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAA;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AAEhD,MAAM,IAAI,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;AAC5F,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,IAAI,OAAO,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC,CAAA;AACtG,MAAM,UAAU,GAAG,GAAG,EAAE,CACtB,IAAI,OAAO,CAAC;IACV,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,CAAC,IAAI,eAAe,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC;CACzG,CAAC,CAAA;AAEJ,iHAAiH;AACjH,MAAM,YAAY,GAAG,CAAC,QAAuB,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,CAAgC,CAAA;AAC/F,QAAQ,CAAC,yBAAyB,EAAE,GAAG,EAAE;IACvC,EAAE,CAAC,yFAAyF,EAAE,GAAG,EAAE;QACjG,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,eAAe,CAAC,EAAE,SAAS,CAAC,YAAY,CAAC,EAAE,IAAI,CAAC,UAAU,CAAC,CAAC,CAAA;QACnF,MAAM,MAAM,GAAG,uBAAuB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QAE5D,iGAAiG;QACjG,8EAA8E;QAC9E,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;YAClD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,EAAE;YACtD,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE;YACxD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE;SACxE,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,mEAAmE,EAAE,GAAG,EAAE;QAC3E,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,CAAA;QAC5B,MAAM,QAAQ,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,QAAQ,CAAC,CAAA;QAC/C,MAAM,MAAM,GAAG,uBAAuB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QAE5D,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QACjC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;QAClC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA,CAAC,YAAY;QACrD,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IACtC,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2EAA2E,EAAE,GAAG,EAAE;QACnF,MAAM,EAAE,GAAG,UAAU,EAAE,CAAA;QACvB,MAAM,MAAM,GAAG,uBAAuB,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,UAAU,CAAC,EAAE,EAAE,CAAC,EAAE,UAAU,CAAC,CAAA;QAE7F,+FAA+F;QAC/F,uCAAuC;QACvC,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;YAClD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE;YAC7C,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE;YACtD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE;SAC1E,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,yDAAyD,EAAE,GAAG,EAAE;QACjE,MAAM,QAAQ,GAAG,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAA;QAChE,MAAM,MAAM,GAAG,uBAAuB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QAE5D,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;YAClD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,EAAE,yBAAyB;YACzE,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE;YAC/C,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC,EAAE;SACtE,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,kDAAkD,EAAE,GAAG,EAAE;QAC1D,MAAM,MAAM,GAAG,IAAI,OAAO,CAAC;YACzB,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE,CAAC,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC;YAC/B,QAAQ,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE;SACrC,CAAC,CAAA;QACF,MAAM,MAAM,GAAG,uBAAuB,CAAC,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,CAAA;QAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,CAAE,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,aAAa,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;IACnE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,QAAQ,GAAG,CAAC,SAAS,CAAC,gBAAgB,CAAC,CAAC,CAAA;QAC9C,MAAM,MAAM,GAAG,uBAAuB,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAA;QAC5D,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAA;IAC/B,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,YAAY,EAAE,GAAG,EAAE;IAC1B,EAAE,CAAC,mDAAmD,EAAE,GAAG,EAAE;QAC3D,MAAM,CAAC,UAAU,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACpF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,2DAA2D,EAAE,GAAG,EAAE;QACnE,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACzG,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wDAAwD,EAAE,GAAG,EAAE;QAChE,MAAM,CAAC,UAAU,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,OAAO,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACrF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oCAAoC,EAAE,GAAG,EAAE;QAC5C,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpC,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,gBAAgB,EAAE,GAAG,EAAE;IAC9B,EAAE,CAAC,6CAA6C,EAAE,GAAG,EAAE;QACrD,MAAM,OAAO,GAAG,cAAc,CAAC,SAAS,CAAC,CAAA;QACzC,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAChE,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,4BAA4B,EAAE,GAAG,EAAE;QACpC,MAAM,OAAO,GAAG,cAAc,CAAC,UAAU,CAAC,CAAA;QAC1C,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAChE,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IACpE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0BAA0B,EAAE,GAAG,EAAE;QAClC,MAAM,OAAO,GAAG,cAAc,CAAC,WAAW,CAAC,CAAA;QAC3C,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;QAC5C,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACnE,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,0CAA0C,EAAE,GAAG,EAAE;QAClD,MAAM,OAAO,GAAG,cAAc,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,MAAM,IAAI,CAAC,CAAC,CAAA;QACzE,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC/D,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,EAAE,SAAS,CAAC,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAA;IACzF,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iEAAiE,EAAE,GAAG,EAAE;QACzE,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QAClE,MAAM,OAAO,GAAG,cAAc,CAAC,GAAG,EAAE;YAClC,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAA;QACzB,CAAC,CAAC,CAAA;QACF,MAAM,CAAC,OAAO,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QACjE,MAAM,CAAC,IAAI,CAAC,CAAC,gBAAgB,EAAE,CAAA;QAC/B,IAAI,CAAC,WAAW,EAAE,CAAA;IACpB,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA;AAEF,QAAQ,CAAC,2BAA2B,EAAE,GAAG,EAAE;IACzC,oGAAoG;IACpG,sGAAsG;IACtG,iEAAiE;IACjE,MAAM,GAAG,GAAG,CAAC,QAAmB,EAAE,EAAE,CAAC,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,eAAe,EAAE,EAAE,CAAkC,CAAA;IAE9G,EAAE,CAAC,8FAA8F,EAAE,KAAK,IAAI,EAAE;QAC5G,MAAM,OAAO,GAAG,yBAAyB,CAAC,EAAE,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC,CAAA;QACpF,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAEpE,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;YAC3D,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE;YACnD,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,EAAE;SACnE,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,iFAAiF,EAAE,KAAK,IAAI,EAAE;QAC/F,MAAM,IAAI,GAAa,EAAE,CAAA;QACzB,MAAM,OAAO,GAAG,yBAAyB,CAAC;YACxC,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;gBAC/B,IAAI,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAA;gBACjD,OAAO,GAAG,CAAA;YACZ,CAAC;SACF,CAAC,CAAA;QACF,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAA;QAErD,MAAM,CAAC,IAAI,CAAC,CAAC,aAAa,CAAC,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC,CAAA;IACnD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,wDAAwD,EAAE,KAAK,IAAI,EAAE;QACtE,MAAM,QAAQ,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,CAAC,SAAS,EAAE,CAAA;QACzC,MAAM,KAAK,GAAG,EAAE,QAAQ,EAA4C,CAAA;QACpE,MAAM,KAAK,GAAG,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,EAAmC,CAAA;QACjF,IAAI,QAA2D,CAAA;QAC/D,MAAM,OAAO,GAAG,yBAAyB,CAAC;YACxC,aAAa,EAAE,KAAK,EAAE,OAAO,EAAE,EAAE;gBAC/B,QAAQ,GAAG,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAA;gBAC/D,OAAO,SAAS,CAAA;YAClB,CAAC;SACF,CAAC,CAAA;QACF,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA;QAEpB,MAAM,CAAC,QAAQ,CAAC,CAAC,aAAa,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,CAAC,CAAA;IACrD,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,8DAA8D,EAAE,KAAK,IAAI,EAAE;QAC5E,MAAM,aAAa,GAAG,EAAE,CAAC,EAAE,CAAC,KAAK,IAAI,EAAE,CAAC,GAAG,CAAC,CAAA;QAC5C,MAAM,OAAO,GAAG,yBAAyB,CAAC,EAAE,aAAa,EAAE,CAAC,CAAA,CAAC,qBAAqB;QAClF,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,UAAU,EAAE,CAAC,CAAC,CAAA;QAC/D,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA;QAEnC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC1B,MAAM,CAAC,aAAa,CAAC,CAAC,GAAG,CAAC,gBAAgB,EAAE,CAAA;IAC9C,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,sFAAsF,EAAE,KAAK,IAAI,EAAE;QACpG,MAAM,OAAO,GAAG,yBAAyB,CAAC,EAAE,OAAO,EAAE,WAAW,EAAE,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC,CAAA;QAC1G,MAAM,EAAE,GAAG,UAAU,EAAE,CAAA;QACvB,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,CAAA;QAErE,kGAAkG;QAClG,0DAA0D;QAC1D,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC;YAC3D,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC,EAAE;YAC7C,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,CAAC,EAAE;YAC/C,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC,EAAE;SAC1E,CAAC,CAAA;IACJ,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,oEAAoE,EAAE,KAAK,IAAI,EAAE;QAClF,MAAM,OAAO,GAAG,yBAAyB,CAAC,EAAE,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,EAAE,CAAC,CAAA;QAC/E,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACpD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA;QAEnC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;IAC5B,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,4EAA4E,EAAE,KAAK,IAAI,EAAE;QAC1F,MAAM,IAAI,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,kBAAkB,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAA;QAClE,MAAM,OAAO,GAAG,yBAAyB,CAAC;YACxC,aAAa,EAAE,KAAK,IAAI,EAAE;gBACxB,MAAM,IAAI,KAAK,CAAC,MAAM,CAAC,CAAA;YACzB,CAAC;SACF,CAAC,CAAA;QACF,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACpD,MAAM,MAAM,GAAG,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA;QAEnC,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAA;QAC1B,MAAM,CAAC,IAAI,CAAC,CAAC,gBAAgB,EAAE,CAAA;QAC/B,IAAI,CAAC,WAAW,EAAE,CAAA;IACpB,CAAC,CAAC,CAAA;IAEF,EAAE,CAAC,+CAA+C,EAAE,KAAK,IAAI,EAAE;QAC7D,MAAM,OAAO,GAAG,yBAAyB,CAAC,EAAE,aAAa,EAAE,KAAK,IAAI,EAAE,CAAC,UAAU,EAAE,CAAC,CAAA;QACpF,MAAM,KAAK,GAAG,GAAG,CAAC,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAA;QACpD,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,CAAE,CAAA;QACjC,MAAM,OAAO,CAAC,KAAK,CAAC,CAAA;QAEpB,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,CAAA,CAAC,yCAAyC;IAClF,CAAC,CAAC,CAAA;AACJ,CAAC,CAAC,CAAA"}

package/dist/src/injection/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Configuration types for context injection, shared by the `ContextInjector` plugin and
+ * `MemoryManager`'s `injection` config.
+ */
+export type { InjectionConfig, InjectionTrigger, InjectionContext } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/injection/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/injection/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,YAAY,EAAE,eAAe,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA"}

package/dist/src/injection/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/src/injection/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/injection/index.ts"],"names":[],"mappings":""}

package/dist/src/injection/message-injection.d.ts

@@ -0,0 +1,65 @@
+import { Message } from '../types/messages.js';
+import type { MessageData } from '../types/messages.js';
+import type { InvokeModelContext } from '../middleware/index.js';
+import type { InjectionMiddlewareOptions, InjectionTrigger, InjectionContext } from './types.js';
+/**
+ * Builds an `InvokeModelStage` `Input` handler that folds {@link InjectionMiddlewareOptions.renderContent}'s
+ * text into the latest user message, ephemerally — the model sees the augmented input for this one call
+ * while the agent's durable history is never touched.
+ *
+ * Runs as an input-phase transformer (`(ctx) => ctx`): it gates on the resolved trigger, asks
+ * `renderContent` for the text, and returns a context with the folded messages. Anything that skips —
+ * the trigger not firing, `renderContent` returning empty, or any callback throwing — returns the
+ * context unchanged so the model call proceeds (fail open). The injected text never enters durable
+ * history because the input phase only rewrites the per-call context, not the agent's stored messages.
+ *
+ * @param opts - The trigger and `renderContent` callback the handler uses
+ * @returns An `InvokeModelStage.Input` handler that returns a (possibly) folded context
+ * @internal Delivery primitive. Reach injection through `ContextInjector` or `MemoryManager`.
+ */
+export declare function createInjectionMiddleware(opts: InjectionMiddlewareOptions): (context: InvokeModelContext) => Promise<InvokeModelContext>;
+/**
+ * Resolves an {@link InjectionTrigger} name or predicate into a single gate predicate over the
+ * {@link InjectionContext}.
+ *
+ * `'userTurn'` maps to {@link isUserTurn} (over `ctx.messages`); `'everyTurn'` to an always-true gate;
+ * a user-supplied predicate is wrapped so that a throw fails open (logs and skips injection rather than
+ * aborting the model call).
+ *
+ * @param trigger - An {@link InjectionTrigger} name, a predicate, or `undefined` (defaults to `'userTurn'`)
+ * @returns A predicate that, given the {@link InjectionContext}, returns whether to inject this call
+ * @internal Delivery primitive. Reach injection through `ContextInjector` or `MemoryManager`.
+ */
+export declare function resolveTrigger(trigger: InjectionTrigger | ((context: InjectionContext) => boolean) | undefined): (context: InjectionContext) => boolean;
+/**
+ * Whether the latest message is a fresh user ask: a `user` message carrying no tool result. This is
+ * the `'userTurn'` policy — it distinguishes a new chat ask from an autonomous tool-result turn.
+ *
+ * @param messages - The current conversation, as data
+ * @returns `true` when the latest message is a plain user ask, otherwise `false`
+ * @internal Delivery primitive. Reach injection through `ContextInjector` or `MemoryManager`.
+ */
+export declare function isUserTurn(messages: MessageData[]): boolean;
+/**
+ * Folds `text` into the most recent `user` message as a {@link TextBlock}, returning a NEW array. Other
+ * messages are returned as-is.
+ *
+ * Folding into the existing user message (rather than inserting a standalone message) keeps role
+ * alternation valid in both chat and the autonomous tool loop. The block is placed to keep the message
+ * valid for the model:
+ * - A plain user ask: the text is **prepended**, leaving the user's own ask in the recency slot — the
+ *   last thing the model reads.
+ * - A tool-result turn (the message carries a `ToolResultBlock`): the text is **appended**,
+ *   because providers require the tool result to be the first content block in the turn that answers a
+ *   tool use.
+ *
+ * {@link Message} fields are readonly, so the target is rebuilt as a new {@link Message}. When there is
+ * no `user` message, the input array is returned unchanged.
+ *
+ * @param messages - The conversation to fold into
+ * @param text - The text to fold into the most recent user message
+ * @returns A new array with the folded message, or the input array when there is no user message
+ * @internal Delivery primitive. Reach injection through `ContextInjector` or `MemoryManager`.
+ */
+export declare function foldIntoLastUserMessage(messages: Message[], text: string): Message[];
+//# sourceMappingURL=message-injection.d.ts.map

package/dist/src/injection/message-injection.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-injection.d.ts","sourceRoot":"","sources":["../../../src/injection/message-injection.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAa,MAAM,sBAAsB,CAAA;AACzD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AAGvD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAA;AAChE,OAAO,KAAK,EAAE,0BAA0B,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAEhG;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,yBAAyB,CACvC,IAAI,EAAE,0BAA0B,GAC/B,CAAC,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,kBAAkB,CAAC,CA0B9D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,GAAG,SAAS,GAC/E,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAgBxC;AAED;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,WAAW,EAAE,GAAG,OAAO,CAG3D;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,EAAE,CA2BpF"}

package/dist/src/injection/message-injection.js

@@ -0,0 +1,134 @@
+import { Message, TextBlock } from '../types/messages.js';
+import { logger } from '../logging/logger.js';
+import { normalizeError } from '../errors.js';
+/**
+ * Builds an `InvokeModelStage` `Input` handler that folds {@link InjectionMiddlewareOptions.renderContent}'s
+ * text into the latest user message, ephemerally — the model sees the augmented input for this one call
+ * while the agent's durable history is never touched.
+ *
+ * Runs as an input-phase transformer (`(ctx) => ctx`): it gates on the resolved trigger, asks
+ * `renderContent` for the text, and returns a context with the folded messages. Anything that skips —
+ * the trigger not firing, `renderContent` returning empty, or any callback throwing — returns the
+ * context unchanged so the model call proceeds (fail open). The injected text never enters durable
+ * history because the input phase only rewrites the per-call context, not the agent's stored messages.
+ *
+ * @param opts - The trigger and `renderContent` callback the handler uses
+ * @returns An `InvokeModelStage.Input` handler that returns a (possibly) folded context
+ * @internal Delivery primitive. Reach injection through `ContextInjector` or `MemoryManager`.
+ */
+export function createInjectionMiddleware(opts) {
+    const trigger = resolveTrigger(opts.trigger);
+    return async (context) => {
+        const agent = context.agent;
+        const injectionContext = {
+            messages: context.messages.map((message) => message.toJSON()),
+            appState: agent.appState,
+            agent,
+        };
+        if (!trigger(injectionContext)) {
+            return context;
+        }
+        let text;
+        try {
+            text = await opts.renderContent(injectionContext);
+        }
+        catch (error) {
+            logger.warn(`reason=<${normalizeError(error).message}> | injection renderContent threw; skipping injection`);
+            return context;
+        }
+        if (!text?.trim()) {
+            return context;
+        }
+        return { ...context, messages: foldIntoLastUserMessage([...context.messages], text) };
+    };
+}
+/**
+ * Resolves an {@link InjectionTrigger} name or predicate into a single gate predicate over the
+ * {@link InjectionContext}.
+ *
+ * `'userTurn'` maps to {@link isUserTurn} (over `ctx.messages`); `'everyTurn'` to an always-true gate;
+ * a user-supplied predicate is wrapped so that a throw fails open (logs and skips injection rather than
+ * aborting the model call).
+ *
+ * @param trigger - An {@link InjectionTrigger} name, a predicate, or `undefined` (defaults to `'userTurn'`)
+ * @returns A predicate that, given the {@link InjectionContext}, returns whether to inject this call
+ * @internal Delivery primitive. Reach injection through `ContextInjector` or `MemoryManager`.
+ */
+export function resolveTrigger(trigger) {
+    if (trigger === undefined || trigger === 'userTurn') {
+        return (context) => isUserTurn(context.messages);
+    }
+    if (trigger === 'everyTurn') {
+        return () => true;
+    }
+    const predicate = trigger;
+    return (context) => {
+        try {
+            return predicate(context);
+        }
+        catch (error) {
+            logger.warn(`reason=<${normalizeError(error).message}> | injection trigger threw; skipping injection`);
+            return false;
+        }
+    };
+}
+/**
+ * Whether the latest message is a fresh user ask: a `user` message carrying no tool result. This is
+ * the `'userTurn'` policy — it distinguishes a new chat ask from an autonomous tool-result turn.
+ *
+ * @param messages - The current conversation, as data
+ * @returns `true` when the latest message is a plain user ask, otherwise `false`
+ * @internal Delivery primitive. Reach injection through `ContextInjector` or `MemoryManager`.
+ */
+export function isUserTurn(messages) {
+    const last = messages[messages.length - 1];
+    return !!last && last.role === 'user' && !last.content.some((block) => 'toolResult' in block);
+}
+/**
+ * Folds `text` into the most recent `user` message as a {@link TextBlock}, returning a NEW array. Other
+ * messages are returned as-is.
+ *
+ * Folding into the existing user message (rather than inserting a standalone message) keeps role
+ * alternation valid in both chat and the autonomous tool loop. The block is placed to keep the message
+ * valid for the model:
+ * - A plain user ask: the text is **prepended**, leaving the user's own ask in the recency slot — the
+ *   last thing the model reads.
+ * - A tool-result turn (the message carries a `ToolResultBlock`): the text is **appended**,
+ *   because providers require the tool result to be the first content block in the turn that answers a
+ *   tool use.
+ *
+ * {@link Message} fields are readonly, so the target is rebuilt as a new {@link Message}. When there is
+ * no `user` message, the input array is returned unchanged.
+ *
+ * @param messages - The conversation to fold into
+ * @param text - The text to fold into the most recent user message
+ * @returns A new array with the folded message, or the input array when there is no user message
+ * @internal Delivery primitive. Reach injection through `ContextInjector` or `MemoryManager`.
+ */
+export function foldIntoLastUserMessage(messages, text) {
+    let targetIndex = -1;
+    for (let i = messages.length - 1; i >= 0; i--) {
+        if (messages[i].role === 'user') {
+            targetIndex = i;
+            break;
+        }
+    }
+    if (targetIndex < 0) {
+        return messages;
+    }
+    const target = messages[targetIndex];
+    const injected = new TextBlock(text);
+    // A tool result must stay the first block in the turn that answers a tool use, so append rather than
+    // prepend when the target carries one.
+    const hasToolResult = target.content.some((block) => block.type === 'toolResultBlock');
+    const content = hasToolResult ? [...target.content, injected] : [injected, ...target.content];
+    const folded = new Message({
+        role: target.role,
+        content,
+        ...(target.metadata !== undefined && { metadata: target.metadata }),
+    });
+    const result = [...messages];
+    result[targetIndex] = folded;
+    return result;
+}
+//# sourceMappingURL=message-injection.js.map

package/dist/src/injection/message-injection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"message-injection.js","sourceRoot":"","sources":["../../../src/injection/message-injection.ts"],"names":[],"mappings":"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"}

package/dist/src/injection/types.d.ts

@@ -0,0 +1,63 @@
+import type { MessageData } from '../types/messages.js';
+import type { LocalAgent } from '../types/agent.js';
+import type { StateStore } from '../state-store.js';
+/**
+ * Determines when injection runs before a model call.
+ *
+ * - `'userTurn'`: only when the latest message is a fresh user ask (a `user` message with no tool
+ *   result) — the common case for chat agents, where it keeps the user's ask the final message the
+ *   model sees.
+ * - `'everyTurn'`: before every model call, including mid-task tool-result turns — for autonomous
+ *   agents that should consult injected context at each step.
+ *
+ * For finer control, pass a predicate as {@link InjectionConfig.trigger} instead.
+ */
+export type InjectionTrigger = 'userTurn' | 'everyTurn';
+/**
+ * The context an injection consumer receives on each model call, passed to `renderContent` and to a
+ * predicate {@link InjectionConfig.trigger}.
+ */
+export interface InjectionContext {
+    /** The current conversation, as data. */
+    messages: MessageData[];
+    /** Durable app state shared across calls, hooks, and tools — read what a tool stashed last turn. */
+    appState: StateStore;
+    /** The agent the injection is attached to (escape hatch for advanced consumers). */
+    agent: LocalAgent;
+}
+/**
+ * Configuration common to every injection consumer: when to inject. What text to inject is a consumer
+ * concern, added by the interfaces that extend this one (e.g. {@link MemoryInjectionConfig}).
+ */
+export interface InjectionConfig {
+    /**
+     * When injection runs. An {@link InjectionTrigger} name selects a built-in policy; a predicate is
+     * the escape hatch — it receives the {@link InjectionContext} and returns whether to inject this
+     * call. A predicate that throws fails open (injection is skipped, the model call proceeds).
+     *
+     * @defaultValue 'userTurn'
+     */
+    trigger?: InjectionTrigger | ((context: InjectionContext) => boolean);
+}
+/**
+ * Options for {@link createInjectionMiddleware}.
+ *
+ * The engine is text-in: it knows nothing about queries, search, or rendering. A consumer supplies a
+ * single {@link InjectionMiddlewareOptions.renderContent} callback that returns the text to fold into
+ * the conversation, and (optionally) a trigger that gates when to do so.
+ *
+ * @internal Engine options. Consumers configure injection via `ContextInjectorConfig` or
+ * `MemoryInjectionConfig`, not this type.
+ */
+export interface InjectionMiddlewareOptions {
+    /**
+     * When to inject. See {@link InjectionConfig.trigger}. Defaults to `'userTurn'`.
+     */
+    trigger?: InjectionTrigger | ((context: InjectionContext) => boolean);
+    /**
+     * Returns the text to fold into the latest user message, or `undefined`/`''` to skip this call. A
+     * callback that throws fails open (injection is skipped, the model call proceeds).
+     */
+    renderContent: (context: InjectionContext) => Promise<string | undefined>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/src/injection/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/injection/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,sBAAsB,CAAA;AACvD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAA;AAEnD;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GAAG,UAAU,GAAG,WAAW,CAAA;AAEvD;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,yCAAyC;IACzC,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,oGAAoG;IACpG,QAAQ,EAAE,UAAU,CAAA;IACpB,oFAAoF;IACpF,KAAK,EAAE,UAAU,CAAA;CAClB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAA;CACtE;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,0BAA0B;IACzC;;OAEG;IACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAA;IACrE;;;OAGG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAC1E"}

package/dist/src/injection/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/injection/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/injection/types.ts"],"names":[],"mappings":""}

package/dist/src/injection/xml.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Minimal XML escaping for folding untrusted text into an XML-shaped block.
+ *
+ * Memory entries and other injected content are frequently user-derived, so interpolating them raw
+ * into `<entry>…</entry>` both breaks the block structurally (a stray `</entry>` or `"`) and opens a
+ * stored-prompt-injection surface. These helpers are deliberately tiny — enough to keep a `<memory>`
+ * block well-formed, not a general-purpose serializer.
+ */
+/**
+ * Escapes text content for placement between XML tags: `&` (first, so later replacements are not
+ * double-escaped), then `<` and `>`.
+ *
+ * @param value - The raw text to escape
+ * @returns The escaped text, safe to place in element content
+ * @internal Used by the memory default formatter
+ */
+export declare function escapeXmlText(value: string): string;
+/**
+ * Escapes a value for placement inside a double-quoted XML attribute: the {@link escapeXmlText} rules
+ * plus `"` and `'`.
+ *
+ * @param value - The raw attribute value to escape
+ * @returns The escaped value, safe to place inside a quoted attribute
+ * @internal Default-format helper; not part of the public surface.
+ */
+export declare function escapeXmlAttr(value: string): string;
+//# sourceMappingURL=xml.d.ts.map

package/dist/src/injection/xml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.d.ts","sourceRoot":"","sources":["../../../src/injection/xml.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEnD"}

package/dist/src/injection/xml.js

@@ -0,0 +1,31 @@
+/**
+ * Minimal XML escaping for folding untrusted text into an XML-shaped block.
+ *
+ * Memory entries and other injected content are frequently user-derived, so interpolating them raw
+ * into `<entry>…</entry>` both breaks the block structurally (a stray `</entry>` or `"`) and opens a
+ * stored-prompt-injection surface. These helpers are deliberately tiny — enough to keep a `<memory>`
+ * block well-formed, not a general-purpose serializer.
+ */
+/**
+ * Escapes text content for placement between XML tags: `&` (first, so later replacements are not
+ * double-escaped), then `<` and `>`.
+ *
+ * @param value - The raw text to escape
+ * @returns The escaped text, safe to place in element content
+ * @internal Used by the memory default formatter
+ */
+export function escapeXmlText(value) {
+    return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+/**
+ * Escapes a value for placement inside a double-quoted XML attribute: the {@link escapeXmlText} rules
+ * plus `"` and `'`.
+ *
+ * @param value - The raw attribute value to escape
+ * @returns The escaped value, safe to place inside a quoted attribute
+ * @internal Default-format helper; not part of the public surface.
+ */
+export function escapeXmlAttr(value) {
+    return escapeXmlText(value).replace(/"/g, '&quot;').replace(/'/g, '&#39;');
+}
+//# sourceMappingURL=xml.js.map

package/dist/src/injection/xml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"xml.js","sourceRoot":"","sources":["../../../src/injection/xml.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,KAAK,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;AACjF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,KAAa;IACzC,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAA;AAC5E,CAAC"}