@juspay/neurolink 12.9.6 → 12.10.0

package/CHANGELOG.md

@@ -1,8 +1,8 @@
-## [12.9.6](https://github.com/juspay/neurolink/compare/v12.9.5...v12.9.6) (2026-09-03)
+## [12.10.0](https://github.com/juspay/neurolink/compare/v12.9.6...v12.10.0) (2026-09-03)
 
-### Bug Fixes
+### Features
 
-- **(mcp):** repair near-miss tool names at the direct external execution boundary ([2a0332d](https://github.com/juspay/neurolink/commit/2a0332d9f60a96858e86a1cce9ae27dafaf7e248))
+- **(artifacts):** Redis and custom stores, range reads, artifact search ([cf59810](https://github.com/juspay/neurolink/commit/cf59810092343b6fadfdcc1557824929d6b2c4e0))
 
 ## [11.2.3](https://github.com/juspay/neurolink/compare/v11.2.2...v11.2.3) (2026-08-19)
 

package/dist/artifacts/artifactBanking.d.ts

@@ -13,8 +13,9 @@
  * Read-back is the tool that already exists: `retrieve_context({ artifactId,
  * offset, limit })` paginates any artifact and reports `totalSize` / `hasMore`.
  * There is no second read tool and no second storage layer — this module is a
- * thin, typed front door onto `LocalTempArtifactStore`, the same store the MCP
- * output normalizer externalizes into.
+ * thin, typed front door onto the instance's artifact store (local temp,
+ * Redis, or injected), the same store the MCP output normalizer externalizes
+ * into.
  *
  * The one thing it adds is that the store no longer has to pre-exist: it is
  * created on first use, whether or not `mcp.outputLimits` was ever configured,
@@ -52,6 +53,9 @@ export declare function bankArtifact(host: NeuroLink, payload: string, options:
  * because a host that asks for the artifact is asking for the artifact.
  * Returns null when the id is unknown or the file is gone.
  *
+ * With a `page`, a backend that supports range reads moves only the window
+ * (see `readArtifactWindow`) — the same path `retrieve_context` takes.
+ *
  * @param page Character window. `offset` defaults to 0, `limit` to the rest.
  */
 export declare function readArtifact(host: NeuroLink, id: string, page?: ArtifactPageRequest): Promise<string | null>;

package/dist/artifacts/artifactBanking.js

@@ -13,8 +13,9 @@
  * Read-back is the tool that already exists: `retrieve_context({ artifactId,
  * offset, limit })` paginates any artifact and reports `totalSize` / `hasMore`.
  * There is no second read tool and no second storage layer — this module is a
- * thin, typed front door onto `LocalTempArtifactStore`, the same store the MCP
- * output normalizer externalizes into.
+ * thin, typed front door onto the instance's artifact store (local temp,
+ * Redis, or injected), the same store the MCP output normalizer externalizes
+ * into.
  *
  * The one thing it adds is that the store no longer has to pre-exist: it is
  * created on first use, whether or not `mcp.outputLimits` was ever configured,
@@ -22,6 +23,7 @@
  *
  * @module artifacts/artifactBanking
  */
+import { readArtifactWindow } from "./artifactReader.js";
 /** Preview length when the caller does not ask for one. */
 const DEFAULT_BANK_PREVIEW_CHARS = 1000;
 /**
@@ -104,20 +106,13 @@ export async function bankArtifact(host, payload, options) {
  * because a host that asks for the artifact is asking for the artifact.
  * Returns null when the id is unknown or the file is gone.
  *
+ * With a `page`, a backend that supports range reads moves only the window
+ * (see `readArtifactWindow`) — the same path `retrieve_context` takes.
+ *
  * @param page Character window. `offset` defaults to 0, `limit` to the rest.
  */
 export async function readArtifact(host, id, page) {
     const store = ensureArtifactStore(host);
-    const content = await store.retrieve(id);
-    if (content === null) {
-        return null;
-    }
-    if (!page) {
-        return content;
-    }
-    const offset = Math.max(0, page.offset ?? 0);
-    if (page.limit === undefined) {
-        return content.slice(offset);
-    }
-    return content.slice(offset, offset + Math.max(0, page.limit));
+    const window = await readArtifactWindow(store, id, page);
+    return window === null ? null : window.content;
 }

package/dist/artifacts/artifactReader.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Artifact reading primitives shared by every backend and every reader.
+ *
+ * Two readers exist — the model's `retrieve_context({ artifactId })` and the
+ * host's `readArtifact()` — and two shipped backends. Everything they agree
+ * on lives here so it is agreed on exactly once:
+ *
+ *  - `readArtifactWindow` is THE paged read. It asks a backend for a window
+ *    when the backend can produce one (`retrieveRange`), and otherwise reads
+ *    the whole payload and slices. A reader never has to know which.
+ *  - `searchArtifactContent` is the literal search over an artifact. It
+ *    returns bounded snippets with character offsets, never whole lines:
+ *    an MCP artifact is usually one compact JSON line, so "the matching line"
+ *    would be the payload the search was meant to avoid reading.
+ *  - `isSafeArtifactId` is the shape check every backend applies before an
+ *    id reaches a path or a key. Ids arrive from the model.
+ *
+ * @module artifacts/artifactReader
+ */
+import type { ArtifactPageRequest, ArtifactSearchResult, ArtifactStore, ArtifactWindow } from "../types/index.js";
+/** Characters used for the quick preview embedded in surrogate results. */
+export declare const DEFAULT_PREVIEW_CHARS = 500;
+/** Matches returned by one artifact search; the rest are counted, not sent. */
+export declare const MAX_ARTIFACT_SEARCH_MATCHES = 50;
+/** Longest search pattern accepted — bounds the work per call. */
+export declare const MAX_SEARCH_PATTERN_CHARS = 200;
+/** True when `id` is shaped like something a backend may look up. */
+export declare function isSafeArtifactId(id: string): boolean;
+/** Head slice of a payload for surrogate headers, ellipsised when cut. */
+export declare function generateArtifactPreview(payload: string, chars?: number): string;
+/** Cut one window out of a payload already in memory. */
+export declare function sliceArtifactWindow(content: string, page?: ArtifactPageRequest): ArtifactWindow;
+/**
+ * Read one window of an artifact through whatever the backend supports.
+ *
+ * With a `page` and a backend that implements `retrieveRange`, only the
+ * window crosses the wire. Otherwise the whole payload is fetched and cut
+ * here. Without a `page` the whole payload is always fetched — a caller that
+ * omits the window is asking for the artifact.
+ *
+ * Returns `null` when the id is unknown, unsafe, or expired.
+ */
+export declare function readArtifactWindow(store: ArtifactStore, id: string, page?: ArtifactPageRequest): Promise<ArtifactWindow | null>;
+/**
+ * Why a search pattern cannot be used, or `undefined` when it can.
+ *
+ * Empty would match at every position; over-long bounds the scan. Both are
+ * reported to the model rather than silently ignored — the whole point of
+ * the artifact search is that "search did not happen" is never invisible.
+ */
+export declare function validateSearchPattern(pattern: string): string | undefined;
+/**
+ * Literal, case-insensitive search over an artifact.
+ *
+ * Regex metacharacters in `pattern` are matched literally — the model's
+ * input is never compiled as a regex, so it cannot be made catastrophic.
+ * Each hit carries the character `offset` of the match (what to pass back as
+ * `offset` for a targeted read), its 1-based line, and a bounded snippet.
+ *
+ * Scanning starts at `from`, so a caller can walk a long payload by passing
+ * `nextSearchOffset` back in. Every match after `from` is counted in
+ * `totalMatches`; only the first `maxMatches` are returned.
+ *
+ * `pattern` must already have passed {@link validateSearchPattern}.
+ */
+export declare function searchArtifactContent(content: string, pattern: string, options?: {
+    from?: number;
+    maxMatches?: number;
+}): ArtifactSearchResult;

package/dist/artifacts/artifactReader.js

@@ -0,0 +1,157 @@
+/**
+ * Artifact reading primitives shared by every backend and every reader.
+ *
+ * Two readers exist — the model's `retrieve_context({ artifactId })` and the
+ * host's `readArtifact()` — and two shipped backends. Everything they agree
+ * on lives here so it is agreed on exactly once:
+ *
+ *  - `readArtifactWindow` is THE paged read. It asks a backend for a window
+ *    when the backend can produce one (`retrieveRange`), and otherwise reads
+ *    the whole payload and slices. A reader never has to know which.
+ *  - `searchArtifactContent` is the literal search over an artifact. It
+ *    returns bounded snippets with character offsets, never whole lines:
+ *    an MCP artifact is usually one compact JSON line, so "the matching line"
+ *    would be the payload the search was meant to avoid reading.
+ *  - `isSafeArtifactId` is the shape check every backend applies before an
+ *    id reaches a path or a key. Ids arrive from the model.
+ *
+ * @module artifacts/artifactReader
+ */
+/** Characters used for the quick preview embedded in surrogate results. */
+export const DEFAULT_PREVIEW_CHARS = 500;
+/** Matches returned by one artifact search; the rest are counted, not sent. */
+export const MAX_ARTIFACT_SEARCH_MATCHES = 50;
+/** Longest search pattern accepted — bounds the work per call. */
+export const MAX_SEARCH_PATTERN_CHARS = 200;
+/** Characters kept on each side of a hit in its snippet. */
+const SNIPPET_CONTEXT_CHARS = 120;
+/**
+ * Ids that may be turned into a path or a key.
+ *
+ * Ids reach the backends straight from the model through `retrieve_context`.
+ * No dots and no separators means `../../etc/passwd` can never become a file
+ * probe, and no glob characters means an id can never widen a key pattern.
+ * Real ids are UUIDs.
+ */
+const SAFE_ARTIFACT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
+/** True when `id` is shaped like something a backend may look up. */
+export function isSafeArtifactId(id) {
+    return SAFE_ARTIFACT_ID.test(id);
+}
+/** Head slice of a payload for surrogate headers, ellipsised when cut. */
+export function generateArtifactPreview(payload, chars = DEFAULT_PREVIEW_CHARS) {
+    if (payload.length <= chars) {
+        return payload;
+    }
+    return `${payload.slice(0, chars)}…`;
+}
+/** Cut one window out of a payload already in memory. */
+export function sliceArtifactWindow(content, page) {
+    const offset = Math.max(0, page?.offset ?? 0);
+    const limit = page?.limit;
+    const window = limit === undefined
+        ? content.slice(offset)
+        : content.slice(offset, offset + Math.max(0, limit));
+    return { content: window, offset, totalLength: content.length };
+}
+/**
+ * Read one window of an artifact through whatever the backend supports.
+ *
+ * With a `page` and a backend that implements `retrieveRange`, only the
+ * window crosses the wire. Otherwise the whole payload is fetched and cut
+ * here. Without a `page` the whole payload is always fetched — a caller that
+ * omits the window is asking for the artifact.
+ *
+ * Returns `null` when the id is unknown, unsafe, or expired.
+ */
+export async function readArtifactWindow(store, id, page) {
+    if (page && store.retrieveRange) {
+        return store.retrieveRange(id, {
+            offset: Math.max(0, page.offset ?? 0),
+            limit: page.limit === undefined ? undefined : Math.max(0, page.limit),
+        });
+    }
+    const content = await store.retrieve(id);
+    if (content === null) {
+        return null;
+    }
+    return sliceArtifactWindow(content, page);
+}
+/**
+ * Why a search pattern cannot be used, or `undefined` when it can.
+ *
+ * Empty would match at every position; over-long bounds the scan. Both are
+ * reported to the model rather than silently ignored — the whole point of
+ * the artifact search is that "search did not happen" is never invisible.
+ */
+export function validateSearchPattern(pattern) {
+    if (pattern.length === 0) {
+        return "Search pattern must not be empty";
+    }
+    if (pattern.length > MAX_SEARCH_PATTERN_CHARS) {
+        return `Search pattern too long (max ${MAX_SEARCH_PATTERN_CHARS} chars)`;
+    }
+    return undefined;
+}
+/**
+ * Literal, case-insensitive search over an artifact.
+ *
+ * Regex metacharacters in `pattern` are matched literally — the model's
+ * input is never compiled as a regex, so it cannot be made catastrophic.
+ * Each hit carries the character `offset` of the match (what to pass back as
+ * `offset` for a targeted read), its 1-based line, and a bounded snippet.
+ *
+ * Scanning starts at `from`, so a caller can walk a long payload by passing
+ * `nextSearchOffset` back in. Every match after `from` is counted in
+ * `totalMatches`; only the first `maxMatches` are returned.
+ *
+ * `pattern` must already have passed {@link validateSearchPattern}.
+ */
+export function searchArtifactContent(content, pattern, options) {
+    const from = Math.max(0, options?.from ?? 0);
+    const maxMatches = options?.maxMatches ?? MAX_ARTIFACT_SEARCH_MATCHES;
+    const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    const regex = new RegExp(escaped, "gi");
+    regex.lastIndex = from;
+    const matches = [];
+    let totalMatches = 0;
+    let nextSearchOffset;
+    // Line numbers are counted incrementally from the start of the payload so
+    // the whole scan stays a single pass.
+    let line = 1;
+    let lineScanPos = 0;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        totalMatches += 1;
+        if (matches.length < maxMatches) {
+            for (let i = lineScanPos; i < match.index; i += 1) {
+                if (content.charCodeAt(i) === 10) {
+                    line += 1;
+                }
+            }
+            lineScanPos = match.index;
+            const snippetOffset = Math.max(0, match.index - SNIPPET_CONTEXT_CHARS);
+            const snippetEnd = Math.min(content.length, match.index + match[0].length + SNIPPET_CONTEXT_CHARS);
+            matches.push({
+                offset: match.index,
+                line,
+                snippetOffset,
+                snippet: content.slice(snippetOffset, snippetEnd),
+            });
+        }
+        else if (nextSearchOffset === undefined) {
+            nextSearchOffset = match.index;
+        }
+        if (match[0].length === 0) {
+            // Unreachable for a non-empty pattern; keeps the loop finite regardless.
+            regex.lastIndex += 1;
+        }
+    }
+    return {
+        matches,
+        matchCount: matches.length,
+        totalMatches,
+        truncated: totalMatches > matches.length,
+        ...(nextSearchOffset === undefined ? {} : { nextSearchOffset }),
+    };
+}

package/dist/artifacts/artifactStore.d.ts

@@ -12,8 +12,9 @@
  *   ArtifactStore (interface) — canonical types in src/lib/types/artifactTypes.ts
  *   LocalTempArtifactStore   — single-process, filesystem-backed implementation
  *
- * Distributed backends (S3, Redis blobs) can be added later by implementing
- * ArtifactStore from types/artifactTypes.ts.
+ * `RedisArtifactStore` is the shared-across-replicas backend; anything else
+ * (S3, a database) implements ArtifactStore and is injected via
+ * `artifacts.store` or `setArtifactStore()`.
  *
  * @module artifacts/artifactStore
  */
@@ -77,7 +78,10 @@ export declare class LocalTempArtifactStore implements ArtifactStore {
      * falls back to probing the payload file itself, so an artifact whose
      * sidecar was lost is still readable with metadata recovered from `stat`.
      *
-     * Returns undefined for an unsafe id without touching the filesystem.
+     * Returns undefined for an unsafe id without touching the filesystem: before
+     * this fallback existed an unknown id simply missed the in-memory map, and
+     * now that a miss probes `join(dir, id + ext)` the id — which arrives from
+     * the model — reaches the path layer. See `isSafeArtifactId`.
      */
     private rehydrate;
 }

package/dist/artifacts/artifactStore.js

@@ -12,8 +12,9 @@
  *   ArtifactStore (interface) — canonical types in src/lib/types/artifactTypes.ts
  *   LocalTempArtifactStore   — single-process, filesystem-backed implementation
  *
- * Distributed backends (S3, Redis blobs) can be added later by implementing
- * ArtifactStore from types/artifactTypes.ts.
+ * `RedisArtifactStore` is the shared-across-replicas backend; anything else
+ * (S3, a database) implements ArtifactStore and is injected via
+ * `artifacts.store` or `setArtifactStore()`.
  *
  * @module artifacts/artifactStore
  */
@@ -22,27 +23,15 @@ import { mkdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { logger } from "../utils/logger.js";
-// Re-export so callers can import everything from one place
+import { generateArtifactPreview, isSafeArtifactId } from "./artifactReader.js";
 // ---------------------------------------------------------------------------
 // LocalTempArtifactStore
 // ---------------------------------------------------------------------------
-/** Characters used for the quick preview embedded in surrogate results. */
-const DEFAULT_PREVIEW_CHARS = 500;
 /**
  * Sidecar written beside every payload so a process that never called
  * `store()` can still resolve the id (see the index-miss path in `retrieve`).
  */
 const META_SUFFIX = ".meta.json";
-/**
- * Ids that may be turned into a path.
- *
- * Before the index-miss fallback existed, an unknown id simply missed the
- * in-memory map and no filesystem lookup happened. Now that a miss probes
- * `join(dir, id + ext)`, the id reaches the path layer — and ids arrive from
- * the model through `retrieve_context`. No dots and no separators means
- * `../../etc/passwd` can never become a probe. Real ids are UUIDs.
- */
-const SAFE_ARTIFACT_ID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/;
 /** Extensions `store()` can produce, in the order the fallback probes them. */
 const PAYLOAD_EXTENSIONS = [".json", ".txt"];
 /**
@@ -130,10 +119,7 @@ export class LocalTempArtifactStore {
                 process.env.NEUROLINK_ARTIFACT_REHYDRATE !== "false";
     }
     generatePreview(payload) {
-        if (payload.length <= DEFAULT_PREVIEW_CHARS) {
-            return payload;
-        }
-        return `${payload.slice(0, DEFAULT_PREVIEW_CHARS)}…`;
+        return generateArtifactPreview(payload);
     }
     async store(payload, meta) {
         await mkdir(this.dir, { recursive: true, mode: 0o700 });
@@ -231,10 +217,13 @@ export class LocalTempArtifactStore {
      * falls back to probing the payload file itself, so an artifact whose
      * sidecar was lost is still readable with metadata recovered from `stat`.
      *
-     * Returns undefined for an unsafe id without touching the filesystem.
+     * Returns undefined for an unsafe id without touching the filesystem: before
+     * this fallback existed an unknown id simply missed the in-memory map, and
+     * now that a miss probes `join(dir, id + ext)` the id — which arrives from
+     * the model — reaches the path layer. See `isSafeArtifactId`.
      */
     async rehydrate(id) {
-        if (!SAFE_ARTIFACT_ID.test(id)) {
+        if (!isSafeArtifactId(id)) {
             logger.debug(`[ArtifactStore] Rejected unsafe artifact id "${id}"`);
             return undefined;
         }

package/dist/artifacts/artifactStoreFactory.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Artifact store factory — picks a backend the way conversation memory does.
+ *
+ * Backend:    `artifacts.store` → `artifacts.storage` → `STORAGE_TYPE` → local
+ * Connection: `artifacts.redisConfig` → conversation memory's `redisConfig`
+ *             → `REDIS_URL` / `REDIS_HOST` … environment variables
+ *
+ * So `STORAGE_TYPE=redis`, which already moves sessions to Redis, moves
+ * artifacts there too, on the same pooled connection, with nothing new to
+ * set. The one thing never inherited is the KEY PREFIX: artifacts get their
+ * own (`neurolink:artifact:`) even when the connection came from the
+ * conversation config or `REDIS_KEY_PREFIX`.
+ *
+ * @module artifacts/artifactStoreFactory
+ */
+import type { ArtifactStorageConfig, ArtifactStorageType, ArtifactStore, RedisStorageConfig } from "../types/index.js";
+/**
+ * The Redis connection described by the environment — the same variables
+ * conversation memory reads, minus `REDIS_KEY_PREFIX`, which names the
+ * conversation keyspace and must not name this one.
+ */
+export declare function readArtifactRedisConfigFromEnv(): RedisStorageConfig;
+/** Which backend `config` and the environment select. */
+export declare function resolveArtifactStorageType(config?: ArtifactStorageConfig): ArtifactStorageType;
+/**
+ * The Redis connection an artifact store should use, with its own key prefix.
+ *
+ * @param config   `artifacts` constructor config
+ * @param fallback conversation memory's `redisConfig`, when one was given
+ */
+export declare function resolveArtifactRedisConfig(config?: ArtifactStorageConfig, fallback?: RedisStorageConfig): RedisStorageConfig;
+/**
+ * Build the artifact store `config` asks for.
+ *
+ * @param config   `artifacts` constructor config
+ * @param fallbackRedis conversation memory's `redisConfig`, consulted for the
+ *   connection when `config.redisConfig` is absent
+ */
+export declare function createArtifactStore(config?: ArtifactStorageConfig, fallbackRedis?: RedisStorageConfig): ArtifactStore;

package/dist/artifacts/artifactStoreFactory.js

@@ -0,0 +1,101 @@
+/**
+ * Artifact store factory — picks a backend the way conversation memory does.
+ *
+ * Backend:    `artifacts.store` → `artifacts.storage` → `STORAGE_TYPE` → local
+ * Connection: `artifacts.redisConfig` → conversation memory's `redisConfig`
+ *             → `REDIS_URL` / `REDIS_HOST` … environment variables
+ *
+ * So `STORAGE_TYPE=redis`, which already moves sessions to Redis, moves
+ * artifacts there too, on the same pooled connection, with nothing new to
+ * set. The one thing never inherited is the KEY PREFIX: artifacts get their
+ * own (`neurolink:artifact:`) even when the connection came from the
+ * conversation config or `REDIS_KEY_PREFIX`.
+ *
+ * @module artifacts/artifactStoreFactory
+ */
+import { logger } from "../utils/logger.js";
+import { LocalTempArtifactStore } from "./artifactStore.js";
+import { DEFAULT_ARTIFACT_KEY_PREFIX, RedisArtifactStore, } from "./redisArtifactStore.js";
+function numberFromEnv(name) {
+    const raw = process.env[name];
+    if (raw === undefined || raw === "") {
+        return undefined;
+    }
+    const value = Number(raw);
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * The Redis connection described by the environment — the same variables
+ * conversation memory reads, minus `REDIS_KEY_PREFIX`, which names the
+ * conversation keyspace and must not name this one.
+ */
+export function readArtifactRedisConfigFromEnv() {
+    const config = {
+        host: process.env.REDIS_HOST,
+        port: numberFromEnv("REDIS_PORT"),
+        password: process.env.REDIS_PASSWORD,
+        db: numberFromEnv("REDIS_DB"),
+        ttl: numberFromEnv("REDIS_TTL"),
+        connectionOptions: {
+            connectTimeout: numberFromEnv("REDIS_CONNECT_TIMEOUT"),
+            maxRetriesPerRequest: numberFromEnv("REDIS_MAX_RETRIES"),
+            retryDelayOnFailover: numberFromEnv("REDIS_RETRY_DELAY"),
+        },
+    };
+    if (process.env.REDIS_URL) {
+        config.url = process.env.REDIS_URL;
+    }
+    return config;
+}
+/** Which backend `config` and the environment select. */
+export function resolveArtifactStorageType(config) {
+    if (config?.storage) {
+        return config.storage;
+    }
+    const fromEnv = process.env.STORAGE_TYPE?.trim().toLowerCase();
+    return fromEnv === "redis" ? "redis" : "local";
+}
+/**
+ * The Redis connection an artifact store should use, with its own key prefix.
+ *
+ * @param config   `artifacts` constructor config
+ * @param fallback conversation memory's `redisConfig`, when one was given
+ */
+export function resolveArtifactRedisConfig(config, fallback) {
+    const source = config?.redisConfig ?? fallback ?? readArtifactRedisConfigFromEnv();
+    return {
+        url: source.url,
+        username: source.username,
+        host: source.host,
+        port: source.port,
+        password: source.password,
+        db: source.db,
+        ttl: source.ttl,
+        connectionOptions: source.connectionOptions,
+        keyPrefix: config?.redisConfig?.keyPrefix ?? DEFAULT_ARTIFACT_KEY_PREFIX,
+    };
+}
+/**
+ * Build the artifact store `config` asks for.
+ *
+ * @param config   `artifacts` constructor config
+ * @param fallbackRedis conversation memory's `redisConfig`, consulted for the
+ *   connection when `config.redisConfig` is absent
+ */
+export function createArtifactStore(config, fallbackRedis) {
+    if (config?.store) {
+        logger.debug("[ArtifactStore] Using the injected artifact store");
+        return config.store;
+    }
+    const storage = resolveArtifactStorageType(config);
+    if (storage === "redis") {
+        const redis = resolveArtifactRedisConfig(config, fallbackRedis);
+        logger.debug("[ArtifactStore] Artifact store backend: redis", {
+            host: redis.host ?? (redis.url ? "(url)" : "localhost"),
+            keyPrefix: redis.keyPrefix,
+        });
+        return new RedisArtifactStore(redis);
+    }
+    logger.debug("[ArtifactStore] Artifact store backend: local-temp");
+    return new LocalTempArtifactStore();
+}

package/dist/artifacts/redisArtifactStore.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Redis Artifact Store
+ *
+ * The artifact backend for more than one machine. `LocalTempArtifactStore`
+ * writes to a pod's own `/tmp`: a replica that did not store an artifact
+ * cannot read it, a redeploy loses all of them, and `cleanup()` can only
+ * expire what its own process wrote. Here every replica sees every artifact,
+ * Redis expires them by TTL, and a paged read moves only the window.
+ *
+ * Layout, under `keyPrefix` (default `neurolink:artifact:`):
+ *
+ *   <prefix><id>        STRING  the payload, verbatim
+ *   <prefix><id>:meta   STRING  JSON `RedisArtifactRecord`
+ *
+ * Both keys carry the same TTL and are written in one MULTI, so an id either
+ * resolves completely or not at all.
+ *
+ * Range reads are honest about units. `retrieve_context` addresses characters;
+ * `GETRANGE` addresses bytes. The record stores the payload's character length
+ * next to its byte length, and only when the two are equal — pure ASCII, which
+ * is what JSON tool output and logs almost always are — is a byte range used
+ * as a character range. Anything else falls back to a whole read and a slice,
+ * which is slower and still correct. A window never starts on the wrong
+ * character.
+ *
+ * The connection is the same pool Redis conversation memory uses, keyed by
+ * host, port and database, so a deployment that already keeps sessions in
+ * Redis adds no connection by keeping artifacts there too.
+ *
+ * @module artifacts/redisArtifactStore
+ */
+import type { ArtifactMeta, ArtifactPageRequest, ArtifactRef, ArtifactStore, ArtifactWindow, RedisStorageConfig } from "../types/index.js";
+/** Key prefix when the caller does not choose one. Never the conversation prefix. */
+export declare const DEFAULT_ARTIFACT_KEY_PREFIX = "neurolink:artifact:";
+/** Expiry when the caller does not choose one, or chooses an unusable one. */
+export declare const DEFAULT_ARTIFACT_TTL_SECONDS = 86400;
+/**
+ * Redis-backed artifact store: shared across replicas, expired by TTL,
+ * range reads for ASCII payloads.
+ *
+ * @example
+ * ```typescript
+ * const store = new RedisArtifactStore({ url: process.env.REDIS_URL });
+ * const neurolink = new NeuroLink({ artifacts: { store } });
+ * // or let NeuroLink build it: { artifacts: { storage: "redis" } }
+ * ```
+ */
+export declare class RedisArtifactStore implements ArtifactStore {
+    private readonly config;
+    private client?;
+    private connecting?;
+    /**
+     * @param config - Connection and key settings. `keyPrefix` defaults to
+     *   `neurolink:artifact:`. `ttl` is seconds and must be positive; it
+     *   defaults to 86400 (24 hours), and zero, negative or non-finite values
+     *   are replaced by that default with a warning — artifacts in Redis always
+     *   expire, there is no "keep forever". `userSessionsKeyPrefix` is
+     *   meaningless here and ignored.
+     */
+    constructor(config?: RedisStorageConfig);
+    generatePreview(payload: string): string;
+    store(payload: string, meta: Omit<ArtifactMeta, "createdAt">): Promise<ArtifactRef>;
+    retrieve(id: string): Promise<string | null>;
+    retrieveRange(id: string, range: ArtifactPageRequest): Promise<ArtifactWindow | null>;
+    delete(id: string): Promise<void>;
+    /**
+     * Nothing to sweep: Redis expires every artifact `ttl` seconds after it was
+     * written, on every replica at once, which is what `cleanup()` on the local
+     * store could never do.
+     */
+    cleanup(olderThanMs: number): Promise<number>;
+    /**
+     * Release this store's reference on the pooled connection.
+     *
+     * Waits for a connect that is still in flight: otherwise the reference it
+     * is about to acquire would be assigned after this returned, and nothing
+     * would ever release it.
+     */
+    close(): Promise<void>;
+    private payloadKey;
+    private metaKey;
+    /** Connect on first use, once, and share the pooled client afterwards. */
+    private getClient;
+}