agentfootprint 10.3.1 → 10.5.0

package/dist/esm/adapters/memory/agentcore.d.ts

@@ -22,6 +22,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
@@ -43,6 +45,35 @@
 import type { ListOptions, ListResult, MemoryStore, PutIfVersionResult, ScoredEntry, SearchOptions } from '../../memory/store/types.js';
 import type { MemoryEntry } from '../../memory/entry/index.js';
 import type { MemoryIdentity } from '../../memory/identity/index.js';
+import { type MemoryWriteOptionName, type MemoryWriteOptions } from '../../memory/store/writeOptions.js';
+/**
+ * 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)
+ */
+export declare function agentCoreNamespaceValue(raw: string): string;
 /** One event as the adapter cares about it: AgentCore's id + the decoded entry. */
 export interface AgentCoreEvent {
     /** AgentCore server-assigned event id (needed to delete it). */
@@ -114,12 +145,35 @@ export declare class UnreadableMemoryEntryError extends TypeError {
  * `DeleteEvent`; tests inject a mock via `_client`.
  */
 export interface AgentCoreLikeClient {
+    /**
+     * `true` when {@link createEvent} forwards `extractionMode` and
+     * `extractionConfig` to `CreateEvent` unchanged. The built-in client does.
+     *
+     * Declared, not assumed: a client written before these fields existed
+     * compiles against the wider input and drops them, and a dropped
+     * `extractionMode: 'SKIP'` sends a turn the caller kept out of long-term
+     * memory INTO extraction. Without this, `AgentCoreStore` honours no write
+     * options and refuses them by name.
+     */
+    readonly forwardsWriteOptions?: true;
     /** Append one entry as an event (server assigns the eventId). */
     createEvent(input: {
         memoryId: string;
         actorId: string;
         sessionId: string;
         entry: MemoryEntry;
+        /**
+         * `CreateEvent`'s own field (`ExtractionMode.SKIP`): store the event in
+         * short-term memory, exclude it from long-term extraction.
+         */
+        extractionMode?: 'SKIP';
+        /**
+         * `CreateEvent`'s own field: `namespaceVariables` are substituted into the
+         * memory's `namespaceTemplates` during long-term extraction.
+         */
+        extractionConfig?: {
+            readonly namespaceVariables: Readonly<Record<string, string>>;
+        };
     }): Promise<void>;
     /** One page of the session's events (newest-first is AgentCore's default). */
     listEvents(input: {
@@ -164,8 +218,14 @@ export interface AgentCoreMemoryRecord {
     readonly score?: number;
     /** Which strategy produced the record (semantic, summary, user-preference, …). */
     readonly memoryStrategyId?: string;
-    /** The namespace it was found in. */
+    /** The namespace it was found in — the first of {@link namespaces}. */
     readonly namespace?: string;
+    /**
+     * Every namespace the record is filed under, as `RetrieveMemoryRecords`
+     * reports them (`MemoryRecordSummary.namespaces`). `search()` keeps a record
+     * only when one of these is the namespace it asked for, or lies under it.
+     */
+    readonly namespaces?: readonly string[];
     /** When AgentCore created it (unix ms), when reported. */
     readonly createdAt?: number;
 }
@@ -184,12 +244,21 @@ export interface AgentCoreStoreOptions {
      * something like `/strategies/{strategyId}/actors/{actorId}`).
      *
      * A function, because the namespace usually contains the actor: it is handed
-     * the resolved AgentCore ids for the identity being searched. Default:
-     * `/actors/{actorId}/sessions/{sessionId}` — the session's own records.
+     * the resolved AgentCore ids for the identity being searched, the identity
+     * itself, and — when the memory binds one (`writeOptions.namespaceScope`) —
+     * the SAME namespace scope its writes are filed under, resolved for this
+     * identity. Build the namespace from that scope
+     * (`({ namespaceScope }) => '/tenants/' + namespaceScope?.tenantid + '/facts'`):
+     * a search given a scope is refused unless every one of its values is a
+     * path segment of the namespace, so a read cannot leave the tenant its
+     * writes were filed under. Default: `/actors/{actorId}/sessions/{sessionId}`
+     * — the session's own records.
      */
     readonly searchNamespace?: (scope: {
         readonly actorId: string;
         readonly sessionId: string;
+        readonly identity: MemoryIdentity;
+        readonly namespaceScope?: Readonly<Record<string, string>>;
     }) => string;
     /**
      * Restrict `search()` to one extraction strategy (semantic, summary,
@@ -199,6 +268,27 @@ export interface AgentCoreStoreOptions {
      * `minScore` / `k` from {@link SearchOptions} are applied to what comes back.
      */
     readonly searchStrategyId?: string;
+    /**
+     * Refuse, by name, every write and search that carries no `namespaceScope`.
+     *
+     * Set it on a store whose every memory is scoped — a multi-tenant
+     * deployment. A memory, a `defineRAG` or a direct call that forgot its scope
+     * is then refused, instead of filing or reading under a namespace no tenant
+     * owns (a template with an empty variable). Default `false`.
+     */
+    readonly requireNamespaceScope?: boolean;
+    /**
+     * Let a search read the records derived from EVERY principal of a tenant.
+     *
+     * Off by default: a search for an identity that names a principal is refused
+     * unless its namespace holds that identity's `actorId` as path segments —
+     * a namespace that stops at the tenant serves one person's extracted facts,
+     * preferences and summaries to another. Set it only when the memory's
+     * strategies file per tenant ON PURPOSE (knowledge the whole tenant shares).
+     * It applies to SCOPED searches only: a search with no scope has no tenant to
+     * stay inside, so it must always hold the actor.
+     */
+    readonly searchAcrossPrincipals?: boolean;
     /** @internal Test injection — skips the SDK require entirely. */
     readonly _client?: AgentCoreLikeClient;
     /** @internal Test injection — the AWS SDK module (to exercise the real shim with a mock SDK). */
@@ -245,11 +335,45 @@ export declare class AgentCoreStore implements MemoryStore {
      * anything.
      */
     readonly 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(): readonly MemoryWriteOptionName[] | undefined;
     private readonly client;
     private readonly memoryId;
     private readonly pageSize;
     private readonly searchNamespace;
     private readonly searchStrategyId;
+    private readonly 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.
+     */
+    private servedScoped;
+    private readonly searchAcrossPrincipals;
+    /** Why the write options cannot be honoured — `undefined` when they can. */
+    private readonly writeOptionsRefusal;
     private closed;
     private readonly signatures;
     private readonly feedbackBag;
@@ -262,13 +386,28 @@ export declare class AgentCoreStore implements MemoryStore {
     /** Walk every event in the session (paginated). */
     private eachEvent;
     get<T = unknown>(identity: MemoryIdentity, id: string): Promise<MemoryEntry<T> | null>;
-    put<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>): Promise<void>;
-    putMany<T = unknown>(identity: MemoryIdentity, entries: readonly MemoryEntry<T>[]): Promise<void>;
+    put<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, options?: MemoryWriteOptions): Promise<void>;
+    /** One event, with the write options already turned into fields (and checked) once. */
+    private createEvent;
+    putMany<T = unknown>(identity: MemoryIdentity, entries: readonly MemoryEntry<T>[], options?: MemoryWriteOptions): Promise<void>;
     /**
      * Emulated optimistic concurrency. AgentCore appends unconditionally; we read-then-write
      * inside a JS critical section — adequate for single-writer-per-session deployments.
      */
-    putIfVersion<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, expectedVersion: number): Promise<PutIfVersionResult>;
+    putIfVersion<T = unknown>(identity: MemoryIdentity, entry: MemoryEntry<T>, expectedVersion: number, options?: MemoryWriteOptions): Promise<PutIfVersionResult>;
+    /**
+     * 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.
+     */
+    private namespaceFor;
+    /**
+     * 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.
+     */
+    private extractionFields;
     list<T = unknown>(identity: MemoryIdentity, options?: ListOptions): Promise<ListResult<T>>;
     delete(identity: MemoryIdentity, id: string): Promise<void>;
     seen(identity: MemoryIdentity, signature: string): Promise<boolean>;
@@ -299,7 +438,8 @@ export declare class AgentCoreStore implements MemoryStore {
      * 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.
@@ -321,4 +461,9 @@ export interface BedrockAgentCoreSdkModule {
     readonly ListEventsCommand?: new (input: unknown) => unknown;
     readonly DeleteEventCommand?: new (input: unknown) => unknown;
     readonly RetrieveMemoryRecordsCommand?: new (input: unknown) => unknown;
+    /**
+     * The SDK's own schema of `CreateEventInput` — read only to learn whether this
+     * SDK MODELS the extraction fields (see `sdkModelsExtraction`).
+     */
+    readonly CreateEventInput$?: unknown;
 }