agentfootprint 10.3.0 → 10.4.0

package/dist/adapters/memory/agentcore.js

@@ -23,6 +23,8 @@
  * "delete the whole session" call. This shapes the adapter:
  *
  *   • `put`  → `CreateEvent` (append; `actorId` + `eventTimestamp` are required).  O(1)
+ *     Its write options become CreateEvent's own fields: `extraction: 'skip'` →
+ *     `extractionMode: 'SKIP'`, `namespaceScope` → `extractionConfig.namespaceVariables`.
  *   • `list` → `ListEvents` (paginated, `includePayloads`).  ← window / episodic memory.  O(page)
  *   • `get(id)` / `delete(id)` → list-then-find by the entry id stored in the blob, since
  *     AgentCore's ids are server-assigned.  **O(events in session)** — fine for typical
@@ -42,10 +44,198 @@
  *          in use.  Emits: N/A (storage adapters don't emit).
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentCoreStore = exports.UnreadableMemoryEntryError = void 0;
+exports.AgentCoreStore = exports.UnreadableMemoryEntryError = exports.agentCoreNamespaceValue = void 0;
 const index_js_1 = require("../../memory/identity/index.js");
 const lazyRequire_js_1 = require("../../lib/lazyRequire.js");
 const storedPreview_js_1 = require("../../lib/storedPreview.js");
+const writeOptions_js_1 = require("../../memory/store/writeOptions.js");
+/** What this store honours when its client forwards CreateEvent's extraction fields. */
+const AGENTCORE_WRITE_OPTIONS = Object.freeze([
+    'extraction',
+    'namespaceScope',
+]);
+/**
+ * ── Namespace variables: AgentCore's domain, checked here ──
+ *
+ * From the AgentCore API reference, `ExtractionConfig.namespaceVariables`: at
+ * most 5 entries; keys 1–32 characters matching
+ * `(?!memoryStrategyId$|actorId$|sessionId$)[a-z][a-z0-9]*`; values 1–64
+ * characters matching `[a-z0-9][a-z0-9-_]*`.
+ *
+ * Checked BEFORE the write rather than left to AgentCore, for one reason: its
+ * `ValidationException` may quote the rejected value, and the value names a
+ * tenant — a refusal here names the variable and the rule, never the value.
+ */
+const MAX_NAMESPACE_VARIABLES = 5;
+/** The refusal of a scope-less write or search on a store that requires one. */
+const MISSING_SCOPE = (what) => `AgentCoreStore: this ${what} carries no \`namespaceScope\`, and the store requires one — it ` +
+    'was built with `requireNamespaceScope: true`, or it has already served scoped calls. It is ' +
+    'refused rather than run under a namespace no tenant owns. Scope the memory that made it ' +
+    '(`defineMemory({ namespaceScope })`).';
+/**
+ * Refuse, before any call, an identity this store cannot address: not an
+ * object, or no `conversationId` — an absent one would encode to ONE session
+ * every such identity shares.
+ */
+function assertAddressable(identity) {
+    if (identity === null || typeof identity !== 'object') {
+        throw new TypeError('AgentCoreStore: an identity is required — got none.');
+    }
+    const { conversationId, tenant, principal } = identity;
+    if (typeof conversationId !== 'string' || conversationId === '') {
+        throw new TypeError('AgentCoreStore: the identity has no `conversationId`. It is refused rather than filed ' +
+            'under one session every such identity would share.');
+    }
+    for (const [name, value] of [
+        ['tenant', tenant],
+        ['principal', principal],
+    ]) {
+        if (value !== undefined && value !== null && typeof value !== 'string') {
+            throw new TypeError(`AgentCoreStore: the identity's \`${name}\` must be a string.`);
+        }
+    }
+}
+/**
+ * Refuse a search namespace that names no place: not a string, empty, or no
+ * path segment at all (`''`, `'/'`) — AgentCore matches a prefix, and an empty
+ * prefix is every record of the memory.
+ */
+function assertNamespace(namespace) {
+    if (typeof namespace !== 'string' || pathOf(namespace).replace(/^\//, '') === '') {
+        throw new TypeError('AgentCoreStore.search(): `searchNamespace` returned no namespace — an empty prefix ' +
+            'matches every record of the memory, so it is refused. Return a namespace with at ' +
+            'least one path segment.');
+    }
+}
+const NAMESPACE_KEY = /^(?!memoryStrategyId$|actorId$|sessionId$)[a-z][a-z0-9]{0,31}$/;
+const NAMESPACE_VALUE = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+const NAMESPACE_VALUE_MAX = 64;
+/** Refuse, by variable name and rule, a scope AgentCore would reject. */
+function checkNamespaceVariables(scope) {
+    const keys = Object.keys(scope);
+    if (keys.length > MAX_NAMESPACE_VARIABLES) {
+        throw new TypeError(`AgentCoreStore: a namespaceScope may carry at most ${MAX_NAMESPACE_VARIABLES} variables ` +
+            `(AgentCore's limit); this one has ${keys.length}.`);
+    }
+    for (const key of keys) {
+        if (!NAMESPACE_KEY.test(key)) {
+            throw new TypeError(`AgentCoreStore: the namespace variable name ${JSON.stringify(key)} is not one ` +
+                'AgentCore admits — 1–32 characters, a lowercase letter then lowercase letters or ' +
+                'digits (and not memoryStrategyId / actorId / sessionId).');
+        }
+        const value = scope[key];
+        if (typeof value !== 'string' || !NAMESPACE_VALUE.test(value)) {
+            throw new TypeError(`AgentCoreStore: the value of namespace variable ${JSON.stringify(key)} is not one ` +
+                'AgentCore admits — 1–64 characters of [a-z0-9-_], starting with a letter or digit. ' +
+                'It is not quoted here: it names a tenant. Map your id with ' +
+                '`agentCoreNamespaceValue(...)`, which is one-to-one and fits this alphabet.');
+        }
+    }
+}
+/**
+ * A scope as the store uses it: read ONCE into a frozen plain copy, so the value
+ * that is checked is the value that is sent — a getter, or an object the
+ * caller's resolver reuses and edits, cannot change it between the two.
+ */
+function frozenScope(scope) {
+    return Object.freeze(Object.fromEntries(Object.entries(scope)));
+}
+/**
+ * A search under a namespace scope must stay inside it — checked by RENDERING,
+ * not by looking: `searchNamespace` is asked again with every value replaced
+ * by a canary, and the two namespaces must agree segment for segment — each
+ * canary's segment holding exactly that variable's real value, every other
+ * segment the same literal. So a namespace that ignores the scope, puts a
+ * variable inside a segment, or merely happens to contain a value elsewhere
+ * (a tenant named like a literal segment) is refused, naming the variable and
+ * never quoting its value.
+ */
+function assertSearchWithinScope(render, namespace, namespaceScope) {
+    const variables = Object.keys(namespaceScope);
+    const nonce = globalThis.crypto.randomUUID();
+    const canaries = variables.map((_, i) => `canary${i}-${nonce}`);
+    const canaryScope = Object.fromEntries(variables.map((v, i) => [v, canaries[i]]));
+    const real = namespace.split('/');
+    const probe = render(canaryScope).split('/');
+    const refuse = (variable) => {
+        throw new TypeError(`AgentCoreStore.search(): the namespace searched does not hold namespace variable ` +
+            `${JSON.stringify(variable)} as a path segment of its own, so it could read records ` +
+            'filed under another tenant’s scope. Build `searchNamespace` from the ' +
+            '`namespaceScope` it is handed, one variable per segment (e.g. ' +
+            '"/tenants/{tenantid}/actors/{actorId}/facts").');
+    };
+    const seen = new Set();
+    if (real.length !== probe.length)
+        refuse(variables[0] ?? 'namespaceScope');
+    probe.forEach((segment, i) => {
+        const at = canaries.indexOf(segment);
+        if (at === -1) {
+            if (real[i] !== segment)
+                refuse(variables[0] ?? 'namespaceScope');
+            return;
+        }
+        const variable = variables[at];
+        if (real[i] !== namespaceScope[variable])
+            refuse(variable);
+        seen.add(variable);
+    });
+    for (const variable of variables)
+        if (!seen.has(variable))
+            refuse(variable);
+}
+/**
+ * Does `namespace` hold `actorId` as whole path segments? (An actor id can
+ * itself contain `/`, its escape.)
+ */
+function holdsActor(namespace, actorId) {
+    return `/${pathOf(namespace).replace(/^\//, '')}/`.includes(`/${actorId}/`);
+}
+/**
+ * A caller's value — a tenant id — in the alphabet AgentCore admits for a
+ * namespace variable, ONE-TO-ONE.
+ *
+ * The alphabet is narrow (`[a-z0-9][a-z0-9-_]*`, at most 64 characters), so the
+ * easy mappings fold: lowercasing merges `Acme` with `acme`, stripping merges
+ * `a.b` with `ab`, truncating merges any two long ids that share a prefix — and
+ * a fold here files two tenants' derived records under one namespace. This is
+ * the same law as the actor and session ids above, in this alphabet:
+ *
+ *   - `[a-z0-9-]` passes through; every other UTF-16 code unit becomes `_`
+ *     plus its four lowercase hex digits (fixed width, so it decodes);
+ *   - every value starts with `v`, so one whose first character had to be
+ *     escaped still starts with a letter — and no two inputs share an output;
+ *   - every value ENDS with `_z`, which cannot occur inside an encoding (an
+ *     `_` there is always followed by four hex digits) — so no tenant's value
+ *     is the beginning of another's (`1` and `12` would otherwise be `v1` and
+ *     `v12`), and a prefix match over namespaces cannot reach a neighbour;
+ *   - too long is REFUSED, never truncated.
+ *
+ * `agentCoreNamespaceValue('acme')` is `'vacme_z'`; `'Acme'` is `'v_0041cme_z'`.
+ * Use the same mapping wherever the namespace is read back (`searchNamespace`).
+ *
+ * @throws {TypeError} for an empty value — an absent tenant is not a tenant
+ * @throws {RangeError} when the encoding exceeds 64 characters (the value is
+ *   not quoted: it names a tenant)
+ */
+function agentCoreNamespaceValue(raw) {
+    if (typeof raw !== 'string' || raw === '') {
+        throw new TypeError('agentCoreNamespaceValue: needs a non-empty string — an absent tenant is not a tenant, ' +
+            'and giving it a stand-in value would share that namespace with whoever is named it.');
+    }
+    let out = 'v';
+    for (let i = 0; i < raw.length; i++) {
+        const ch = raw[i];
+        out += /[a-z0-9-]/.test(ch) ? ch : `_${raw.charCodeAt(i).toString(16).padStart(4, '0')}`;
+    }
+    out += '_z';
+    if (out.length > NAMESPACE_VALUE_MAX) {
+        throw new RangeError(`agentCoreNamespaceValue: this value encodes to ${out.length} characters, over AgentCore's ` +
+            `${NAMESPACE_VALUE_MAX}. It is not truncated to fit — two ids truncated to one value ` +
+            'share a namespace. The value is not quoted here: it names a tenant.');
+    }
+    return out;
+}
+exports.agentCoreNamespaceValue = agentCoreNamespaceValue;
 /**
  * Thrown when an event carries a blob that is **present but unreadable** where a
  * `MemoryEntry` should be.
@@ -257,11 +447,47 @@ class AgentCoreStore {
      * anything.
      */
     ranksBy = 'server-text';
+    /**
+     * **Both write options, translated to `CreateEvent`'s own fields:**
+     *
+     *   `extraction: 'skip'`   → `extractionMode: 'SKIP'` — the event stays in
+     *                            short-term memory and is excluded from
+     *                            long-term extraction.
+     *   `namespaceScope`       → `extractionConfig: { namespaceVariables }` —
+     *                            substituted into the memory's
+     *                            `namespaceTemplates` during extraction, which
+     *                            is how one tenant's derived records stay in
+     *                            that tenant's namespace.
+     *
+     * Absent — and both refused by name — when they could not reach AgentCore:
+     * an injected client that does not declare `forwardsWriteOptions`, or an
+     * installed SDK too old to MODEL the two fields (its serializer would drop
+     * them without a word). The variables are checked here against AgentCore's
+     * documented domain before anything is sent (see `checkNamespaceVariables`).
+     *
+     * A getter, not a field: a wrapper built by spreading this store
+     * (`{ ...store, put }`) does not copy it — and a wrapper that does not carry
+     * the third argument must not carry the declaration either.
+     */
+    get writeOptions() {
+        return this.writeOptionsRefusal === undefined ? AGENTCORE_WRITE_OPTIONS : undefined;
+    }
     client;
     memoryId;
     pageSize;
     searchNamespace;
     searchStrategyId;
+    requireNamespaceScope;
+    /**
+     * Set by the first write or search that carries a scope: from then on this
+     * store is a SCOPED store, and a call without one is refused — a second
+     * memory, a `defineRAG` or a direct call that forgot its scope never reads
+     * or files across the tenants the first one kept apart.
+     */
+    servedScoped = false;
+    searchAcrossPrincipals;
+    /** Why the write options cannot be honoured — `undefined` when they can. */
+    writeOptionsRefusal;
     closed = false;
     // In-process shadow state for things AgentCore doesn't surface natively.
     signatures = new Map();
@@ -275,12 +501,20 @@ class AgentCoreStore {
             options.searchNamespace ??
                 (({ actorId, sessionId }) => `/actors/${actorId}/sessions/${sessionId}`);
         this.searchStrategyId = options.searchStrategyId;
-        if (options._client)
-            this.client = options._client;
-        else if (options.client)
-            this.client = options.client;
-        else
-            this.client = createAgentCoreClient(options.region, options._sdk);
+        this.requireNamespaceScope = options.requireNamespaceScope === true;
+        this.searchAcrossPrincipals = options.searchAcrossPrincipals === true;
+        const injected = options._client ?? options.client;
+        this.client = injected ?? createAgentCoreClient(options.region, options._sdk);
+        this.writeOptionsRefusal =
+            this.client.forwardsWriteOptions === true
+                ? undefined
+                : injected !== undefined
+                    ? 'its injected client does not declare `forwardsWriteOptions: true`, so it may drop ' +
+                        "CreateEvent's `extractionMode` / `extractionConfig`. Declare it on the client once it " +
+                        'forwards both fields unchanged'
+                    : "the installed `@aws-sdk/client-bedrock-agentcore` does not model CreateEvent's " +
+                        '`extractionMode` / `extractionConfig`, and its serializer drops a field it does not ' +
+                        'model. Upgrade the SDK';
     }
     // MemoryIdentity → AgentCore (actorId, sessionId). The actor is the user/tenant; the
     // session is the conversation. Both are derived deterministically, id-safe and
@@ -294,9 +528,10 @@ class AgentCoreStore {
     sessionId(identity) {
         // One field, so no joiner — but `sessionId` admits no `/`, so it escapes with
         // `_` instead. `-` stays verbatim in both, which is what keeps a UUID a UUID.
-        return boundedId(escapeIdSegment(identity.conversationId ?? '', '_'), SESSION_ID_MAX, 'session');
+        return boundedId(escapeIdSegment(identity.conversationId, '_'), SESSION_ID_MAX, 'session');
     }
     scope(identity) {
+        assertAddressable(identity);
         return {
             memoryId: this.memoryId,
             actorId: this.actorId(identity),
@@ -309,6 +544,7 @@ class AgentCoreStore {
     // a copy of the version where a `/` inside a tenant donated a field boundary
     // — two different identities sharing one dedup set and one feedback bag.
     shadowKey(identity) {
+        assertAddressable(identity);
         return (0, index_js_1.identityNamespace)(identity);
     }
     feedbackKey(identity, id) {
@@ -345,25 +581,40 @@ class AgentCoreStore {
             return null;
         return found;
     }
-    async put(identity, entry) {
+    async put(identity, entry, options) {
         this.ensureOpen('put');
+        await this.createEvent(identity, entry, this.extractionFields(options));
+    }
+    /** One event, with the write options already turned into fields (and checked) once. */
+    async createEvent(identity, entry, extraction) {
         if (entry.ttl !== undefined && entry.ttl <= Date.now())
             return;
-        await this.client.createEvent({ ...this.scope(identity), entry: entry });
+        await this.client.createEvent({
+            ...this.scope(identity),
+            entry: entry,
+            ...extraction,
+        });
     }
-    async putMany(identity, entries) {
+    async putMany(identity, entries, options) {
         this.ensureOpen('putMany');
         // AgentCore has no batch-write API; per-session events are conceptually ordered, so
-        // sequentialize and let the SDK retry policy handle backoff.
+        // sequentialize and let the SDK retry policy handle backoff. The options ride
+        // every event of the batch — a batch is N writes, each asked the same thing,
+        // and turned into fields ONCE, so no await between events can change them.
+        if (entries.length === 0)
+            return;
+        const extraction = this.extractionFields(options);
         for (const entry of entries)
-            await this.put(identity, entry);
+            await this.createEvent(identity, entry, extraction);
     }
     /**
      * Emulated optimistic concurrency. AgentCore appends unconditionally; we read-then-write
      * inside a JS critical section — adequate for single-writer-per-session deployments.
      */
-    async putIfVersion(identity, entry, expectedVersion) {
+    async putIfVersion(identity, entry, expectedVersion, options) {
         this.ensureOpen('putIfVersion');
+        // Refused BEFORE the read, so an unhonoured option never costs a list.
+        const extraction = this.extractionFields(options);
         const current = await this.get(identity, entry.id);
         if (current === null) {
             if (expectedVersion !== 0)
@@ -372,9 +623,86 @@ class AgentCoreStore {
         else if (current.version !== expectedVersion) {
             return { applied: false, currentVersion: current.version };
         }
-        await this.put(identity, entry);
+        await this.createEvent(identity, entry, extraction);
         return { applied: true };
     }
+    /**
+     * The namespace one search reads — rendered by `searchNamespace` and refused
+     * by name when it could read beyond this identity: a wildcard, a namespace
+     * that does not hold the scope segment for segment, or one that stops above
+     * this identity's actor while the identity names a principal.
+     */
+    namespaceFor(identity, ids, given) {
+        // An empty scope asks for nothing — the same rule writes follow
+        // (`requestedWriteOptions`) — so it is treated as no scope at all.
+        const copied = given === undefined ? undefined : frozenScope(given);
+        const namespaceScope = copied === undefined || Object.keys(copied).length === 0 ? undefined : copied;
+        if (namespaceScope === undefined && (this.requireNamespaceScope || this.servedScoped)) {
+            throw new TypeError(MISSING_SCOPE('search'));
+        }
+        if (namespaceScope !== undefined)
+            this.servedScoped = true;
+        if (namespaceScope !== undefined)
+            checkNamespaceVariables(namespaceScope);
+        const render = (scope) => this.searchNamespace({
+            actorId: ids.actorId,
+            sessionId: ids.sessionId,
+            identity,
+            ...(scope !== undefined && { namespaceScope: scope }),
+        });
+        const namespace = render(namespaceScope);
+        assertNamespace(namespace);
+        if (namespace.includes('*')) {
+            throw new TypeError('AgentCoreStore.search(): `searchNamespace` returned a namespace containing `*`. ' +
+                'Results are kept only when they are filed at that namespace or under it, and a ' +
+                'wildcard cannot be checked that way — so it is refused rather than matching nothing. ' +
+                'Name the namespace exactly.');
+        }
+        if (namespaceScope !== undefined)
+            assertSearchWithinScope(render, namespace, namespaceScope);
+        // The actor is required when the identity names a principal — and on EVERY
+        // unscoped search: with no scope to confine it, the actor is the only thing
+        // that keeps the read on this identity (a namespace template rendered with
+        // no tenant collapses to a prefix every tenant shares).
+        // `searchAcrossPrincipals` widens a SCOPED search to the tenant's
+        // principals; with no scope there is no tenant to stay inside, so it never
+        // lifts the actor requirement there.
+        const actorRequired = namespaceScope === undefined ||
+            (identity.principal !== undefined && !this.searchAcrossPrincipals);
+        if (actorRequired && !holdsActor(namespace, ids.actorId)) {
+            throw new TypeError('AgentCoreStore.search(): the namespace searched does not hold this identity’s ' +
+                '`actorId`, so it would read records AgentCore derived from every principal it ' +
+                'covers. Put `{actorId}` in the strategy’s namespace template and in ' +
+                '`searchNamespace` (e.g. "/tenants/{tenantid}/actors/{actorId}/facts"), or set ' +
+                '`searchAcrossPrincipals: true` if the memory is shared on purpose.');
+        }
+        return namespace;
+    }
+    /**
+     * The write options as `CreateEvent`'s own fields — or a refusal by name for
+     * any this store's client cannot carry. The ONE place the vendor-neutral
+     * names become AWS's.
+     */
+    extractionFields(options) {
+        (0, writeOptions_js_1.refuseUnhonouredWriteOptions)('AgentCoreStore', this.writeOptions, options, this.writeOptionsRefusal ?? '');
+        const asked = (0, writeOptions_js_1.requestedWriteOptions)(options);
+        // Copy FIRST, then decide on the copy — the same rule as a search: an empty
+        // copy is no scope, whatever the caller's object reported a moment earlier.
+        const given = options?.namespaceScope;
+        const copied = given === undefined ? undefined : frozenScope(given);
+        const scope = copied === undefined || Object.keys(copied).length === 0 ? undefined : copied;
+        if (scope === undefined && (this.requireNamespaceScope || this.servedScoped)) {
+            throw new TypeError(MISSING_SCOPE('write'));
+        }
+        if (scope !== undefined)
+            this.servedScoped = true;
+        if (scope !== undefined)
+            checkNamespaceVariables(scope);
+        return {
+            ...(asked.includes('extraction') && { extractionMode: 'SKIP' }),
+            ...(scope !== undefined && { extractionConfig: { namespaceVariables: scope } }),
+        };
+    }
     async list(identity, options = {}) {
         this.ensureOpen('list');
         const page = await this.client.listEvents({
@@ -465,7 +793,8 @@ class AgentCoreStore {
      * preferences. The ids therefore belong to AgentCore, not to entries you
      * `put()`, and `store.get(entry.id)` will not find them. They arrive as
      * entries so ranking code needs no special case, with `metadata.source`
-     * saying plainly where they came from.
+     * saying plainly where they came from, and each value is `{ content }` —
+     * the record's text where every memory formatter reads it.
      *
      * Filters: `searchStrategyId` and the namespace reach AgentCore's own side;
      * `k`, `minScore` and `tiers` are applied to what comes back.
@@ -489,15 +818,24 @@ class AgentCoreStore {
         }
         const scope = this.scope(identity);
         const k = options.k ?? 10;
+        const namespace = this.namespaceFor(identity, scope, options.namespaceScope);
         const page = await this.client.retrieveRecords({
             memoryId: this.memoryId,
-            namespace: this.searchNamespace({ actorId: scope.actorId, sessionId: scope.sessionId }),
+            namespace,
             searchQuery: text,
             maxResults: k,
             ...(this.searchStrategyId !== undefined && { memoryStrategyId: this.searchStrategyId }),
         });
         const scored = [];
         for (const record of page.records) {
+            // `namespace` is a PREFIX to AgentCore ("namespaces that start with the
+            // provided prefix"), so `/tenants/v1` also returns `/tenants/v12`'s
+            // records. Keep only what is filed AT the namespace asked for or under
+            // it — and drop a record that names no namespace, which cannot be shown
+            // to belong here, or that may be filed under ANOTHER actor (see
+            // `filedUnder`).
+            if (!filedUnder(record, namespace, scope.actorId))
+                continue;
             const score = record.score ?? 0;
             if (options.minScore !== undefined && score < options.minScore)
                 continue;
@@ -508,7 +846,13 @@ class AgentCoreStore {
             const createdAt = record.createdAt ?? Date.now();
             const entry = {
                 id: record.memoryRecordId,
-                value: record.content,
+                // The store's record shape, `{ content }` — never the bare string.
+                // Both prompt formatters read the text off `.content` (the memory
+                // flavour as a message, the rag flavour as a passage), so a bare string
+                // rendered as an EMPTY block: the record was found and the model never
+                // saw it. No `role`: nobody said this; AgentCore derived it.
+                // Text only: a client outside the type hands back no non-string.
+                value: { content: typeof record.content === 'string' ? record.content : '' },
                 version: 1,
                 createdAt,
                 updatedAt: createdAt,
@@ -541,6 +885,24 @@ class AgentCoreStore {
     }
 }
 exports.AgentCoreStore = AgentCoreStore;
+/**
+ * Does the installed SDK model CreateEvent's `extractionMode` and
+ * `extractionConfig`? Its serializer drops a field it does not model, without a
+ * word, so an older SDK would accept the write options and send neither.
+ *
+ * Read off the SDK's own schema of the input (`CreateEventInput$`, whose member
+ * names include both in 3.1152.0); anything that cannot be read that way counts
+ * as "no" — the options are then refused by name, never sent into a drop.
+ */
+function sdkModelsExtraction(mod) {
+    const schema = mod.CreateEventInput$;
+    if (!Array.isArray(schema))
+        return false;
+    const members = schema.find((part) => Array.isArray(part) && part.includes('memoryId'));
+    return (members !== undefined &&
+        members.includes('extractionMode') &&
+        members.includes('extractionConfig'));
+}
 /**
  * Pull the MemoryEntry out of an AgentCore event's `payload` (a single `blob`
  * document) — this adapter's ONE decode step, and therefore the only place that
@@ -617,7 +979,10 @@ function createAgentCoreClient(region, injected) {
         return sdk.send(new Ctor(input));
     };
     return {
-        async createEvent({ memoryId, actorId, sessionId, entry }) {
+        // The two extraction fields below are forwarded as they are — but only an
+        // SDK that MODELS them sends them, so the declaration follows the SDK.
+        ...(sdkModelsExtraction(mod) && { forwardsWriteOptions: true }),
+        async createEvent({ memoryId, actorId, sessionId, entry, extractionMode, extractionConfig }) {
             // The entry is stored as a single `blob` document (PayloadType.blob =
             // __DocumentType), and it goes in as JSON TEXT, not as the object.
             // Field-learned on the session store and true of every blob this service
@@ -633,6 +998,13 @@ function createAgentCoreClient(region, injected) {
                 sessionId,
                 eventTimestamp: new Date(),
                 payload: [{ blob: JSON.stringify(entry) }],
+                // `CreateEventInput`'s own names (`ExtractionMode.SKIP`,
+                // `ExtractionConfig.namespaceVariables`), present only when asked —
+                // an event without them is extracted exactly as before.
+                ...(extractionMode !== undefined && { extractionMode }),
+                ...(extractionConfig !== undefined && {
+                    extractionConfig: { namespaceVariables: { ...extractionConfig.namespaceVariables } },
+                }),
             });
         },
         async listEvents({ memoryId, actorId, sessionId, maxResults, nextToken }) {
@@ -676,7 +1048,14 @@ function createAgentCoreClient(region, injected) {
             }));
             const records = (r?.memoryRecordSummaries ?? []).map((s) => {
                 const content = typeof s.content === 'string' ? s.content : s.content?.text ?? '';
-                const namespaceValue = Array.isArray(s.namespace) ? s.namespace[0] : s.namespace;
+                const namespaces = (Array.isArray(s.namespaces)
+                    ? s.namespaces
+                    : Array.isArray(s.namespace)
+                        ? s.namespace
+                        : typeof s.namespace === 'string'
+                            ? [s.namespace]
+                            : []).filter((n) => typeof n === 'string');
+                const namespaceValue = namespaces[0];
                 const createdAt = s.createdAt === undefined ? undefined : new Date(s.createdAt).getTime();
                 return {
                     memoryRecordId: s.memoryRecordId ?? '',
@@ -684,6 +1063,7 @@ function createAgentCoreClient(region, injected) {
                     ...(typeof s.score === 'number' && { score: s.score }),
                     ...(s.memoryStrategyId !== undefined && { memoryStrategyId: s.memoryStrategyId }),
                     ...(typeof namespaceValue === 'string' && { namespace: namespaceValue }),
+                    ...(namespaces.length > 0 && { namespaces }),
                     ...(createdAt !== undefined && Number.isFinite(createdAt) && { createdAt }),
                 };
             });
@@ -691,4 +1071,39 @@ function createAgentCoreClient(region, injected) {
         },
     };
 }
+/** A namespace compared as a path: repeated `/` collapsed, a trailing one dropped. */
+function pathOf(namespace) {
+    return namespace.replace(/\/{2,}/g, '/').replace(/\/$/, '');
+}
+/** What the start of another actor's id extending this one looks like. */
+const ACTOR_ESCAPE_AHEAD = /^[0-9A-F]{4}/;
+/**
+ * Is `record` filed AT `asked` or under it? Compared on whole path segments —
+ * repeated and trailing `/` ignored on both sides — because AgentCore's
+ * `namespace` filter is a string prefix, and `/tenants/v1` must not admit
+ * `/tenants/v12`.
+ *
+ * One more case, because an actor id can hold a `/`: its escape is `/` + four
+ * hex digits (`bob@x.com` → `bob/0040x/002Ecom`), so another actor's id can
+ * EXTEND this one by whole segments (`bob@x.com.au` adds `/002Eau`). When the
+ * namespace asked for ends with this identity's `actorId`, a record filed under
+ * a continuation that starts with four uppercase hex digits may be that other
+ * actor's — and is dropped. A sub-namespace of your own that starts that way
+ * is dropped too (put a literal segment after `{actorId}`), never served across
+ * actors. That literal must not itself start with four uppercase hex digits,
+ * or the guard cannot tell it from another actor's id.
+ */
+function filedUnder(record, asked, actorId) {
+    const base = pathOf(asked);
+    const guardActor = base.endsWith(actorId);
+    const filed = record.namespaces ?? (record.namespace !== undefined ? [record.namespace] : []);
+    return filed.some((ns) => {
+        const n = pathOf(ns);
+        if (n === base)
+            return true;
+        if (!n.startsWith(`${base}/`))
+            return false;
+        return !(guardActor && ACTOR_ESCAPE_AHEAD.test(n.slice(base.length + 1)));
+    });
+}
 //# sourceMappingURL=agentcore.js.map