@strands-agents/sdk 1.4.0 → 1.6.0

package/dist/src/vended-memory-stores/bedrock-knowledge-base/store.js

@@ -0,0 +1,370 @@
+import { BedrockAgentRuntimeClient, RetrieveCommand } from '@aws-sdk/client-bedrock-agent-runtime';
+import { BedrockAgentClient, IngestKnowledgeBaseDocumentsCommand, } from '@aws-sdk/client-bedrock-agent';
+import { v7 as uuidv7 } from 'uuid';
+import { logger } from '../../logging/logger.js';
+const DEFAULT_MAX_SEARCH_RESULTS = 10;
+/** Converts a caller metadata value into a Bedrock attribute value, or `undefined` if unsupported. */
+function toAttributeValue(value) {
+    if (typeof value === 'string')
+        return { type: 'STRING', stringValue: value };
+    if (typeof value === 'number')
+        return { type: 'NUMBER', numberValue: value };
+    if (typeof value === 'boolean')
+        return { type: 'BOOLEAN', booleanValue: value };
+    if (Array.isArray(value) && value.length > 0 && value.every((item) => typeof item === 'string')) {
+        return { type: 'STRING_LIST', stringListValue: value };
+    }
+    return undefined;
+}
+/**
+ * A {@link MemoryStore} backed by Amazon Bedrock Knowledge Bases. Supports semantic search via
+ * Retrieve and document ingestion via IngestKnowledgeBaseDocuments for CUSTOM and S3 data sources.
+ *
+ * @example
+ * ```typescript
+ * import { BedrockKnowledgeBaseStore } from '@strands-agents/sdk/vended-memory-stores/bedrock-knowledge-base'
+ *
+ * const store = new BedrockKnowledgeBaseStore({
+ *   config: {
+ *     knowledgeBaseId: 'KB123',
+ *     dataSourceType: 'CUSTOM',
+ *     dataSourceId: 'DS456',
+ *   },
+ *   scope: 'user-abc',
+ *   writable: true,
+ * })
+ *
+ * const results = await store.search('what are my preferences?')
+ * const { documentId } = await store.add('User prefers dark mode')
+ * ```
+ */
+export class BedrockKnowledgeBaseStore {
+    name;
+    description;
+    maxSearchResults;
+    writable;
+    extraction;
+    _runtimeClient;
+    _agentClient;
+    _s3Client;
+    _s3Config;
+    _knowledgeBaseId;
+    _dataSourceType;
+    _dataSourceId;
+    /**
+     * Logical namespace isolating documents: applied as a metadata filter on {@link search} and stamped
+     * on writes via {@link add}. Unlike {@link name}, it is not a store-identity field, so it never
+     * affects `MemoryManager` routing. For per-tenant isolation, construct one store per scope — cheap,
+     * since they can share a single {@link BedrockKnowledgeBaseConfig}.
+     */
+    scope;
+    /** Metadata attribute key used for scope-based filtering. */
+    scopeMetadataKey;
+    /**
+     * Explicit retrieval filter. When set, it overrides the scope-derived filter for {@link search}.
+     * Note the asymmetry: an explicit filter affects search only; writes always scope by {@link scope}.
+     */
+    filter;
+    constructor(options) {
+        const { config, scope, name, description, writable, maxSearchResults, filter, extraction } = options;
+        this.name = name;
+        if (description !== undefined)
+            this.description = description;
+        if (maxSearchResults !== undefined) {
+            if (maxSearchResults < 1) {
+                throw new Error('BedrockKnowledgeBaseStore: maxSearchResults must be at least 1.');
+            }
+            this.maxSearchResults = maxSearchResults;
+        }
+        this.writable = writable ?? false;
+        if (extraction !== undefined)
+            this.extraction = extraction;
+        this._runtimeClient = config.runtimeClient ?? new BedrockAgentRuntimeClient({});
+        this._agentClient = config.agentClient;
+        this._s3Client = config.s3?.client;
+        this._s3Config = config.s3;
+        this._knowledgeBaseId = config.knowledgeBaseId;
+        this._dataSourceType = config.dataSourceType;
+        this._dataSourceId = config.dataSourceId;
+        if (this.writable)
+            this._validateWriteConfig();
+        this.scope = scope;
+        this.scopeMetadataKey = config.scopeMetadataKey ?? 'namespace';
+        this.filter = filter;
+    }
+    /**
+     * Resolves the effective retrieval filter for a search: an explicit {@link filter} wins; otherwise
+     * one is derived from {@link scope} / {@link scopeMetadataKey}.
+     */
+    _resolveFilter() {
+        if (this.filter)
+            return this.filter;
+        if (this.scope)
+            return { equals: { key: this.scopeMetadataKey, value: this.scope } };
+        return undefined;
+    }
+    /**
+     * Searches the knowledge base for entries matching the query.
+     *
+     * @param query - The search query text
+     * @param options - Optional search configuration
+     * @returns Matching memory entries ordered by relevance. Each entry's `metadata` includes
+     *   user-provided attributes plus two reserved synthetic keys: `_relevanceScore` (number) and
+     *   `_sourceLocation` (Bedrock retrieval location object).
+     */
+    async search(query, options) {
+        if (options?.maxSearchResults !== undefined && options.maxSearchResults < 1) {
+            throw new Error('BedrockKnowledgeBaseStore: maxSearchResults must be at least 1.');
+        }
+        const limit = options?.maxSearchResults || this.maxSearchResults || DEFAULT_MAX_SEARCH_RESULTS;
+        const filter = this._resolveFilter();
+        let response;
+        try {
+            response = await this._runtimeClient.send(new RetrieveCommand({
+                knowledgeBaseId: this._knowledgeBaseId,
+                retrievalQuery: { text: query },
+                retrievalConfiguration: {
+                    vectorSearchConfiguration: {
+                        numberOfResults: limit,
+                        ...(filter && { filter }),
+                    },
+                },
+            }));
+        }
+        catch (error) {
+            logger.error(`store=<${this.name}>, knowledgeBaseId=<${this._knowledgeBaseId}>, error=<${error}> | knowledge base retrieve failed`, error);
+            throw error;
+        }
+        return (response.retrievalResults ?? []).map((result) => {
+            const metadata = {};
+            if (result.metadata) {
+                for (const [key, value] of Object.entries(result.metadata)) {
+                    metadata[key] = value;
+                }
+            }
+            if (result.location) {
+                metadata._sourceLocation = result.location;
+            }
+            if (result.score != null) {
+                metadata._relevanceScore = result.score;
+            }
+            return {
+                content: result.content?.text ?? '',
+                metadata,
+            };
+        });
+    }
+    /**
+     * Ingests `content` (with optional `metadata`) into the knowledge base.
+     *
+     * Only `CUSTOM` and `S3` data sources support this — they are the sole `dataSourceType`s that
+     * accept direct ingestion (`IngestKnowledgeBaseDocuments`). `OTHER` backends sync from an external
+     * store or are query-only, so the store is read-only and `add` is unavailable. Requires
+     * `dataSourceId` (and, for `S3`, an `s3` config); see {@link BedrockKnowledgeBaseStoreConfig}.
+     *
+     * @param content - The text content to ingest
+     * @param metadata - Optional metadata attributes to attach to the document
+     * @returns The document identifier (UUID for CUSTOM, s3:// URI for S3)
+     */
+    async add(content, metadata) {
+        if (!this.writable) {
+            throw new Error('BedrockKnowledgeBaseStore: store is not writable. Set writable: true in config to enable add().');
+        }
+        if (!content.trim()) {
+            throw new Error('BedrockKnowledgeBaseStore: content must not be empty.');
+        }
+        const { dataSourceId, dataSourceType } = this._validateWriteConfig();
+        // S3 and CUSTOM data sources accept fundamentally different documents. S3 ingests objects, so
+        // its document references objects uploaded to S3 first; CUSTOM ingests the text inline. Either
+        // way the store mints the document's identifier (CUSTOM: a UUID; S3: the content object's URI)
+        // and returns it, so the caller has a stable handle to the document Bedrock now tracks.
+        let document;
+        let documentId;
+        if (dataSourceType === 'S3') {
+            const objectUris = await this._uploadS3Objects(content, metadata);
+            document = this._buildS3Document(objectUris);
+            documentId = objectUris.contentUri;
+        }
+        else {
+            documentId = uuidv7();
+            document = this._buildCustomDocument(documentId, content, metadata);
+        }
+        try {
+            await this._getAgentClient().send(new IngestKnowledgeBaseDocumentsCommand({
+                knowledgeBaseId: this._knowledgeBaseId,
+                dataSourceId,
+                documents: [document],
+            }));
+        }
+        catch (error) {
+            logger.error(`store=<${this.name}>, knowledgeBaseId=<${this._knowledgeBaseId}>, dataSourceId=<${dataSourceId}>, dataSourceType=<${dataSourceType}>, error=<${error}> | knowledge base document ingestion failed`, error);
+            throw error;
+        }
+        return { documentId };
+    }
+    /**
+     * Uploads the objects that back one S3 ingestion and returns their `s3://` URIs.
+     *
+     * A single `add` produces up to *two* objects — hence the plural name and the multi-URI return:
+     * - `contentUri`: the content itself, uploaded as a `.txt` object. Always written.
+     * - `sidecarUri`: a `<object-key>.metadata.json` sidecar carrying scope/metadata, written *only*
+     *   when there is any to attach (so it's optional in the return). Unlike a `CUSTOM` document, an
+     *   S3 document can't carry attributes inline, so the sidecar is Bedrock's out-of-band convention
+     *   for attaching them: it sits beside the content object and Bedrock pairs the two by name.
+     *
+     * Bedrock reads and indexes these objects on ingestion.
+     *
+     * Note: uploads are not transactional. If the sidecar upload (or the subsequent ingestion) fails
+     * after the content object lands, the uploaded object(s) remain in the bucket un-ingested. They are
+     * inert — a later data-source sync may pick them up, or they can be cleaned up out of band.
+     */
+    async _uploadS3Objects(content, metadata) {
+        const s3 = this._s3Config;
+        const prefix = s3.prefix.endsWith('/') ? s3.prefix : `${s3.prefix}/`;
+        const key = `${prefix}${uuidv7()}.txt`;
+        const contentUri = await this._putObject(s3, key, content, 'text/plain; charset=utf-8');
+        const attributes = this._buildS3SidecarAttributes(metadata);
+        if (Object.keys(attributes).length === 0) {
+            return { contentUri };
+        }
+        // The sidecar must sit beside the source object and be named `<object-key>.metadata.json`.
+        const sidecar = JSON.stringify({ metadataAttributes: attributes });
+        const sidecarUri = await this._putObject(s3, `${key}.metadata.json`, sidecar, 'application/json');
+        return { contentUri, sidecarUri };
+    }
+    /** Uploads a single object to the configured bucket and returns its `s3://` URI. */
+    async _putObject(s3, key, body, contentType) {
+        try {
+            const { PutObjectCommand } = await import('@aws-sdk/client-s3');
+            const client = await this._getS3Client();
+            await client.send(new PutObjectCommand({ Bucket: s3.bucket, Key: key, Body: body, ContentType: contentType }));
+        }
+        catch (error) {
+            logger.error(`store=<${this.name}>, uri=<s3://${s3.bucket}/${key}>, error=<${error}> | S3 upload failed before ingestion`, error);
+            throw error;
+        }
+        return `s3://${s3.bucket}/${key}`;
+    }
+    /**
+     * Builds a document for an `S3` data source from the URIs produced by {@link _uploadS3Objects}.
+     *
+     * Takes both URIs because an S3 document references objects by location rather than carrying data
+     * inline: `contentUri` becomes the document's content (the object to index), and `sidecarUri`,
+     * when present, becomes its metadata (an `S3_LOCATION` pointing at the sidecar). With no
+     * scope/metadata there's no sidecar, so `sidecarUri` is omitted and the document carries no
+     * metadata.
+     */
+    _buildS3Document({ contentUri, sidecarUri, }) {
+        const document = {
+            content: {
+                dataSourceType: 'S3',
+                s3: { s3Location: { uri: contentUri } },
+            },
+        };
+        if (sidecarUri) {
+            document.metadata = {
+                type: 'S3_LOCATION',
+                s3Location: { uri: sidecarUri },
+            };
+        }
+        return document;
+    }
+    /**
+     * Resolves scope and caller metadata into a flat list of key-value pairs, handling collision
+     * detection and unsupported-type filtering. Shared by both CUSTOM (inline attributes) and S3
+     * (sidecar) document builders.
+     */
+    _resolveAttributes(metadata) {
+        const attrs = [];
+        if (this.scope) {
+            attrs.push({ key: this.scopeMetadataKey, value: { type: 'STRING', stringValue: this.scope } });
+        }
+        if (metadata) {
+            for (const [key, value] of Object.entries(metadata)) {
+                if (this.scope && key === this.scopeMetadataKey) {
+                    logger.warn(`store=<${this.name}>, key=<${key}> | dropping metadata key that collides with scopeMetadataKey`);
+                    continue;
+                }
+                const attributeValue = toAttributeValue(value);
+                if (attributeValue) {
+                    attrs.push({ key, value: attributeValue });
+                }
+                else {
+                    logger.debug(`store=<${this.name}>, key=<${key}> | dropping metadata value of unsupported type`);
+                }
+            }
+        }
+        return attrs;
+    }
+    /**
+     * Builds a document for a `CUSTOM` data source: the text ingested inline, with the scope and any
+     * caller metadata attached as inline attributes for retrieval filtering. The caller supplies
+     * `documentId` (so it can return that same id to its own caller) and it becomes the document's
+     * `customDocumentIdentifier`.
+     */
+    _buildCustomDocument(documentId, content, metadata) {
+        const attrs = this._resolveAttributes(metadata);
+        const document = {
+            content: {
+                dataSourceType: 'CUSTOM',
+                custom: {
+                    customDocumentIdentifier: { id: documentId },
+                    sourceType: 'IN_LINE',
+                    inlineContent: {
+                        type: 'TEXT',
+                        textContent: { data: content },
+                    },
+                },
+            },
+        };
+        if (attrs.length > 0) {
+            document.metadata = {
+                type: 'IN_LINE_ATTRIBUTE',
+                inlineAttributes: attrs.map(({ key, value }) => ({ key, value })),
+            };
+        }
+        return document;
+    }
+    /**
+     * Builds the `metadataAttributes` map for an S3 `.metadata.json` sidecar from the scope and caller
+     * metadata. Returns an empty map when there's nothing to attach — {@link _uploadS3Objects} treats
+     * that as "no sidecar" and skips writing the second object.
+     */
+    _buildS3SidecarAttributes(metadata) {
+        const attrs = this._resolveAttributes(metadata);
+        const attributes = {};
+        for (const { key, value } of attrs) {
+            attributes[key] = { value, includeForEmbedding: false };
+        }
+        return attributes;
+    }
+    _validateWriteConfig() {
+        if (this._dataSourceType !== 'CUSTOM' && this._dataSourceType !== 'S3') {
+            throw new Error(`BedrockKnowledgeBaseStore: add requires dataSourceType 'CUSTOM' or 'S3', but it is '${this._dataSourceType ?? 'undefined'}'. ` +
+                "'OTHER' backends are read-only.");
+        }
+        if (!this._dataSourceId) {
+            throw new Error('BedrockKnowledgeBaseStore: dataSourceId is required for write operations. ' +
+                'Provide it in the config to enable add().');
+        }
+        if (this._dataSourceType === 'S3' && !this._s3Config) {
+            throw new Error("BedrockKnowledgeBaseStore: s3 config is required when dataSourceType is 'S3'. " +
+                'Provide bucket and prefix to enable add().');
+        }
+        return { dataSourceId: this._dataSourceId, dataSourceType: this._dataSourceType };
+    }
+    async _getS3Client() {
+        if (!this._s3Client) {
+            const { S3Client: S3ClientImpl } = await import('@aws-sdk/client-s3');
+            this._s3Client = new S3ClientImpl({});
+        }
+        return this._s3Client;
+    }
+    _getAgentClient() {
+        if (!this._agentClient) {
+            this._agentClient = new BedrockAgentClient({});
+        }
+        return this._agentClient;
+    }
+}
+//# sourceMappingURL=store.js.map

package/dist/src/vended-memory-stores/bedrock-knowledge-base/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../../../../src/vended-memory-stores/bedrock-knowledge-base/store.ts"],"names":[],"mappings":"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"}

package/dist/src/vended-plugins/context-injector/__tests__/plugin.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=plugin.test.d.ts.map

package/dist/src/vended-plugins/context-injector/__tests__/plugin.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.test.d.ts","sourceRoot":"","sources":["../../../../../src/vended-plugins/context-injector/__tests__/plugin.test.ts"],"names":[],"mappings":""}

package/dist/src/vended-plugins/context-injector/__tests__/plugin.test.js

@@ -0,0 +1,96 @@
+import { describe, it, expect, vi } from 'vitest';
+import { ContextInjector } from '../plugin.js';
+import { InvokeModelStage } from '../../../middleware/index.js';
+import { Message, TextBlock } from '../../../types/messages.js';
+import { createMockAgent } from '../../../__fixtures__/agent-helpers.js';
+const user = (text) => new Message({ role: 'user', content: [new TextBlock(text)] });
+const assistant = (text) => new Message({ role: 'assistant', content: [new TextBlock(text)] });
+// Builds a mock agent that captures addMiddleware registrations, with a real appState/cancelSignal.
+function makeAgent() {
+    const addMiddleware = vi.fn();
+    const agent = createMockAgent({ extra: { addMiddleware } });
+    return { agent, addMiddleware };
+}
+describe('ContextInjector', () => {
+    describe('plugin interface', () => {
+        it('defaults to the strands:context-injector name', () => {
+            expect(new ContextInjector({ renderContent: async () => 'x' }).name).toBe('strands:context-injector');
+        });
+        it('honors a custom name (so multiple injectors can be told apart)', () => {
+            expect(new ContextInjector({ name: 'now', renderContent: async () => 'x' }).name).toBe('now');
+        });
+        it('registers an InvokeModelStage input middleware on initAgent', () => {
+            const { agent, addMiddleware } = makeAgent();
+            new ContextInjector({ renderContent: async () => 'x' }).initAgent(agent);
+            expect(addMiddleware).toHaveBeenCalledTimes(1);
+            expect(addMiddleware.mock.calls[0][0]).toBe(InvokeModelStage.Input);
+            expect(typeof addMiddleware.mock.calls[0][1]).toBe('function');
+        });
+    });
+    describe('registered handler', () => {
+        // Runs the handler the plugin registered, with a context backed by the mock agent.
+        async function run(plugin, messages) {
+            const { agent, addMiddleware } = makeAgent();
+            plugin.initAgent(agent);
+            const handler = addMiddleware.mock.calls[0][1];
+            return handler({ messages, agent });
+        }
+        it('folds renderContent() text into the latest user message', async () => {
+            const result = await run(new ContextInjector({ renderContent: async () => 'INJECTED' }), [
+                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('skips on a non-user turn by default (userTurn trigger)', async () => {
+            const renderContent = vi.fn(async () => 'x');
+            const input = [user('ask'), assistant('reply')];
+            const result = await run(new ContextInjector({ renderContent }), input);
+            expect(renderContent).not.toHaveBeenCalled();
+            expect(result.messages).toBe(input);
+        });
+        it("'everyTurn' injects regardless of the latest role", async () => {
+            const result = await run(new ContextInjector({ trigger: 'everyTurn', renderContent: async () => 'INJECTED' }), [
+                user('ask'),
+                assistant('reply'),
+            ]);
+            // No later user message than index 0, so the fold targets it.
+            expect(result.messages.map((m) => m.toJSON())).toStrictEqual([
+                { role: 'user', content: [{ text: 'INJECTED' }, { text: 'ask' }] },
+                { role: 'assistant', content: [{ text: 'reply' }] },
+            ]);
+        });
+        it('exposes appState and the agent to renderContent', async () => {
+            const { agent, addMiddleware } = makeAgent();
+            let sawAgent = false;
+            let sawAppState = false;
+            new ContextInjector({
+                renderContent: async (ctx) => {
+                    sawAgent = ctx.agent === agent;
+                    sawAppState = ctx.appState === agent.appState;
+                    return undefined;
+                },
+            }).initAgent(agent);
+            const handler = addMiddleware.mock.calls[0][1];
+            await handler({ messages: [user('ask')], agent });
+            expect(sawAgent).toBe(true);
+            expect(sawAppState).toBe(true);
+        });
+        it('fails open (passes context through) when renderContent throws', async () => {
+            const result = await run(new ContextInjector({
+                renderContent: async () => {
+                    throw new Error('boom');
+                },
+            }), [assistant('prior'), user('ask')]);
+            // Unchanged: the original messages, no injected block.
+            expect(result.messages.map((m) => m.toJSON())).toStrictEqual([
+                { role: 'assistant', content: [{ text: 'prior' }] },
+                { role: 'user', content: [{ text: 'ask' }] },
+            ]);
+        });
+    });
+});
+//# sourceMappingURL=plugin.test.js.map

package/dist/src/vended-plugins/context-injector/__tests__/plugin.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.test.js","sourceRoot":"","sources":["../../../../../src/vended-plugins/context-injector/__tests__/plugin.test.ts"],"names":[],"mappings":"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"}

package/dist/src/vended-plugins/context-injector/index.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Context-injection plugin for Strands Agents.
+ *
+ * Provides the {@link ContextInjector} plugin, which folds just-in-time text into the model input
+ * before each call without touching durable history.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { ContextInjector } from '@strands-agents/sdk/vended-plugins/context-injector'
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [
+ *     new ContextInjector({
+ *       renderContent: async ({ messages }) => `<context>${derive(messages)}</context>`,
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export { ContextInjector } from './plugin.js';
+export type { ContextInjectorConfig } from './plugin.js';
+export type { InjectionTrigger, InjectionContext } from '../../injection/types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/src/vended-plugins/context-injector/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/vended-plugins/context-injector/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAC7C,YAAY,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AACxD,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA"}

package/dist/src/vended-plugins/context-injector/index.js

@@ -0,0 +1,23 @@
+/**
+ * Context-injection plugin for Strands Agents.
+ *
+ * Provides the {@link ContextInjector} plugin, which folds just-in-time text into the model input
+ * before each call without touching durable history.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { ContextInjector } from '@strands-agents/sdk/vended-plugins/context-injector'
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [
+ *     new ContextInjector({
+ *       renderContent: async ({ messages }) => `<context>${derive(messages)}</context>`,
+ *     }),
+ *   ],
+ * })
+ * ```
+ */
+export { ContextInjector } from './plugin.js';
+//# sourceMappingURL=index.js.map

package/dist/src/vended-plugins/context-injector/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/vended-plugins/context-injector/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA"}

package/dist/src/vended-plugins/context-injector/plugin.d.ts

@@ -0,0 +1,55 @@
+import type { Plugin } from '../../plugins/plugin.js';
+import type { LocalAgent } from '../../types/agent.js';
+import type { InjectionTrigger, InjectionContext } from '../../injection/types.js';
+/** Configuration for the {@link ContextInjector} plugin. */
+export interface ContextInjectorConfig {
+    /**
+     * Plugin name, for logging and duplicate detection. Defaults to `'strands:context-injector'`. Set a
+     * distinct name when registering more than one injector so they can be told apart.
+     */
+    name?: string;
+    /**
+     * When to inject. An {@link InjectionTrigger} name selects a built-in policy (`'userTurn'` —
+     * default — or `'everyTurn'`); a predicate over the {@link InjectionContext} is the escape hatch. A
+     * predicate that throws fails open (injection is skipped).
+     *
+     * @defaultValue 'userTurn'
+     */
+    trigger?: InjectionTrigger | ((context: InjectionContext) => boolean);
+    /**
+     * Renders the text to inject for this call, or `undefined`/`''` to skip. The text reaches the model
+     * verbatim, so it is a prompt-injection surface: escape any attacker-influenced fields yourself. A
+     * callback that throws fails open (injection is skipped, the model call proceeds).
+     */
+    renderContent: (context: InjectionContext) => Promise<string | undefined>;
+}
+/**
+ * Plugin that injects just-in-time context into the model input before each call.
+ *
+ * Before each model call, the plugin asks {@link ContextInjectorConfig.renderContent} for text and
+ * makes it available to the model for that call, gated by {@link ContextInjectorConfig.trigger}. The
+ * injected text is ephemeral: it augments the model input for that one call and never persists into the
+ * durable conversation or session.
+ *
+ * @example
+ * ```typescript
+ * import { Agent } from '@strands-agents/sdk'
+ * import { ContextInjector } from '@strands-agents/sdk/vended-plugins/context-injector'
+ *
+ * const agent = new Agent({
+ *   model,
+ *   plugins: [new ContextInjector({ renderContent: async () => `<now>${new Date().toISOString()}</now>` })],
+ * })
+ * ```
+ *
+ * @remarks
+ * Multiple injectors may be registered; each contributes its text independently, in plugin-registration
+ * order.
+ */
+export declare class ContextInjector implements Plugin {
+    readonly name: string;
+    private readonly _config;
+    constructor(config: ContextInjectorConfig);
+    initAgent(agent: LocalAgent): void;
+}
+//# sourceMappingURL=plugin.d.ts.map

package/dist/src/vended-plugins/context-injector/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../../../src/vended-plugins/context-injector/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,yBAAyB,CAAA;AACrD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAA;AAGtD,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAA;AAElF,4DAA4D;AAC5D,MAAM,WAAW,qBAAqB;IACpC;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;;;OAMG;IACH,OAAO,CAAC,EAAE,gBAAgB,GAAG,CAAC,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,CAAA;IACrE;;;;OAIG;IACH,aAAa,EAAE,CAAC,OAAO,EAAE,gBAAgB,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAA;CAC1E;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,qBAAa,eAAgB,YAAW,MAAM;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAuB;gBAEnC,MAAM,EAAE,qBAAqB;IAKzC,SAAS,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;CAUnC"}