@juspay/neurolink 12.0.5 → 12.2.0

package/dist/agent/taskChecklist.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Task checklist primitive (N1) — session-scoped, compaction-proof.
+ *
+ * A long-running agent that plans in prose loses the plan the moment the
+ * conversation is summarized. This keeps the plan OUT of the message list:
+ * checklist state lives in a module-level Map keyed by sessionId, so
+ * compaction — which only ever rewrites messages — cannot touch it. Every
+ * `tasks_*` tool returns the WHOLE list, so the first call after a compaction
+ * re-anchors the model for free; there is no re-injection machinery to get
+ * wrong (N1.3 is satisfied structurally, not by a mechanism).
+ *
+ * The host reads the same state synchronously via `getChecklistState()`, which
+ * is what makes a completeness gate ("no pending items may survive this
+ * stage") one line of host code with no LLM in the loop.
+ *
+ * Registration is opt-in (`NeuroLink.registerTaskTools()`), and goes through
+ * `host.registerTool()` so the tools land in the "user-defined" category —
+ * the only one that reaches the LLM's tool schema.
+ */
+import type { NeuroLink } from "../neurolink.js";
+import type { ChecklistCommandCountsSource, ChecklistDelegateCountsSource, ChecklistState, MCPExecutableTool } from "../types/index.js";
+/**
+ * Let the async-delegation primitive feed `delegatesPending` / `delegatesReady`
+ * into every checklist result, so the model learns a worker finished from any
+ * `tasks_list` — without this module importing delegation (which would make a
+ * cycle) and without a polling loop.
+ */
+export declare function setChecklistDelegateCountsSource(source: ChecklistDelegateCountsSource | undefined): void;
+/**
+ * Let the background-command primitive feed `commandsRunning` /
+ * `commandsFinished` into every checklist result — the same notification
+ * channel the delegate counters use, so the model learns "the build finished"
+ * from any `tasks_list` without this module importing the command runtime
+ * (which would make a cycle) and without a polling loop.
+ */
+export declare function setChecklistCommandCountsSource(source: ChecklistCommandCountsSource | undefined): void;
+/**
+ * Which checklist a tool call belongs to.
+ *
+ * Execution context wins: a worker created with the shared tool registry runs
+ * the host's registered tool closure but arrives with its OWN sessionId, and
+ * that worker's checklist must not merge into its parent's. The host's
+ * `setToolContext()` session is the next authority, and a per-host key is the
+ * last resort so a host that never declared a session still gets ONE list
+ * instead of a new one per call.
+ */
+export declare function resolveChecklistSessionId(host: NeuroLink, context?: unknown): string;
+/** Never throws: an unknown session simply has an empty checklist. */
+export declare function getChecklistState(sessionId: string): ChecklistState;
+/** Drop one session's checklist. Returns whether there was one to drop. */
+export declare function clearChecklistState(sessionId: string): boolean;
+/**
+ * The three model-facing checklist tools, bound to `host` for session
+ * resolution. Register them with `host.registerTool()` (see
+ * `NeuroLink.registerTaskTools()`), never on the tool registry directly:
+ * only the "user-defined" category reaches the LLM's tool schema.
+ */
+export declare function createChecklistTools(host: NeuroLink): Record<string, MCPExecutableTool>;

package/dist/agent/taskChecklist.js

@@ -0,0 +1,322 @@
+/**
+ * Task checklist primitive (N1) — session-scoped, compaction-proof.
+ *
+ * A long-running agent that plans in prose loses the plan the moment the
+ * conversation is summarized. This keeps the plan OUT of the message list:
+ * checklist state lives in a module-level Map keyed by sessionId, so
+ * compaction — which only ever rewrites messages — cannot touch it. Every
+ * `tasks_*` tool returns the WHOLE list, so the first call after a compaction
+ * re-anchors the model for free; there is no re-injection machinery to get
+ * wrong (N1.3 is satisfied structurally, not by a mechanism).
+ *
+ * The host reads the same state synchronously via `getChecklistState()`, which
+ * is what makes a completeness gate ("no pending items may survive this
+ * stage") one line of host code with no LLM in the loop.
+ *
+ * Registration is opt-in (`NeuroLink.registerTaskTools()`), and goes through
+ * `host.registerTool()` so the tools land in the "user-defined" category —
+ * the only one that reaches the LLM's tool schema.
+ */
+import { z } from "zod";
+import { logger } from "../utils/logger.js";
+/** Module-level on purpose: compaction rewrites messages, never a module map. */
+const checklists = new Map();
+const STATUSES = [
+    "pending",
+    "in_progress",
+    "done",
+    "closed",
+];
+/** Ids the engine hands out: t1, t2, … — never accepted from the model. */
+const ID_PREFIX = "t";
+/**
+ * A session id the engine invented for a single tool call: NeuroLink's
+ * tool-context merge defaults to `fallback-${Date.now()}` when no session was
+ * declared anywhere. Honouring it would file every model tool call under a
+ * different checklist — a silently empty list — so it is ignored in favour of
+ * a stable per-host key.
+ *
+ * The registry's other placeholder (a bare `randomUUID()` minted in
+ * `createExecutionContext` when a DIRECT `executeTool()` call carries no
+ * session) is indistinguishable from a host that genuinely uses UUIDs as
+ * session ids, so it is honoured as given: programmatic callers pass
+ * `authContext: { sessionId }`.
+ */
+const SYNTHETIC_SESSION_ID = /^fallback-\d+$/;
+const hostDefaultSessions = new WeakMap();
+let hostDefaultCounter = 0;
+/** Set by the delegation primitive; absent means "no background workers". */
+let delegateCountsSource;
+/** Set by the background-command primitive; absent means "no commands". */
+let commandCountsSource;
+/**
+ * Let the async-delegation primitive feed `delegatesPending` / `delegatesReady`
+ * into every checklist result, so the model learns a worker finished from any
+ * `tasks_list` — without this module importing delegation (which would make a
+ * cycle) and without a polling loop.
+ */
+export function setChecklistDelegateCountsSource(source) {
+    delegateCountsSource = source;
+}
+function delegateCountsFor(sessionId) {
+    if (!delegateCountsSource) {
+        return { pending: 0, ready: 0 };
+    }
+    try {
+        return delegateCountsSource(sessionId);
+    }
+    catch (error) {
+        logger.warn("[TaskChecklist] Delegate counts source failed — reporting 0", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { pending: 0, ready: 0 };
+    }
+}
+/**
+ * Let the background-command primitive feed `commandsRunning` /
+ * `commandsFinished` into every checklist result — the same notification
+ * channel the delegate counters use, so the model learns "the build finished"
+ * from any `tasks_list` without this module importing the command runtime
+ * (which would make a cycle) and without a polling loop.
+ */
+export function setChecklistCommandCountsSource(source) {
+    commandCountsSource = source;
+}
+function commandCountsFor(sessionId) {
+    if (!commandCountsSource) {
+        return { running: 0, finished: 0 };
+    }
+    try {
+        return commandCountsSource(sessionId);
+    }
+    catch (error) {
+        logger.warn("[TaskChecklist] Command counts source failed — reporting 0", {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return { running: 0, finished: 0 };
+    }
+}
+function defaultSessionIdFor(host) {
+    const existing = hostDefaultSessions.get(host);
+    if (existing) {
+        return existing;
+    }
+    hostDefaultCounter += 1;
+    const created = `checklist-default-${hostDefaultCounter}`;
+    hostDefaultSessions.set(host, created);
+    return created;
+}
+function readSessionId(source) {
+    const value = source?.sessionId;
+    return typeof value === "string" ? value.trim() : "";
+}
+/**
+ * Which checklist a tool call belongs to.
+ *
+ * Execution context wins: a worker created with the shared tool registry runs
+ * the host's registered tool closure but arrives with its OWN sessionId, and
+ * that worker's checklist must not merge into its parent's. The host's
+ * `setToolContext()` session is the next authority, and a per-host key is the
+ * last resort so a host that never declared a session still gets ONE list
+ * instead of a new one per call.
+ */
+export function resolveChecklistSessionId(host, context) {
+    const contextRecord = context && typeof context === "object"
+        ? context
+        : undefined;
+    const fromContext = readSessionId(contextRecord);
+    if (fromContext && !SYNTHETIC_SESSION_ID.test(fromContext)) {
+        return fromContext;
+    }
+    const fromHost = readSessionId(host.getToolContext());
+    if (fromHost && !SYNTHETIC_SESSION_ID.test(fromHost)) {
+        return fromHost;
+    }
+    return defaultSessionIdFor(host);
+}
+function cloneState(state) {
+    return {
+        sessionId: state.sessionId,
+        items: state.items.map((item) => ({ ...item })),
+        updatedAt: state.updatedAt,
+    };
+}
+function emptyState(sessionId) {
+    return { sessionId, items: [], updatedAt: 0 };
+}
+/** Never throws: an unknown session simply has an empty checklist. */
+export function getChecklistState(sessionId) {
+    const state = checklists.get(sessionId);
+    return state ? cloneState(state) : emptyState(sessionId);
+}
+/** Drop one session's checklist. Returns whether there was one to drop. */
+export function clearChecklistState(sessionId) {
+    return checklists.delete(sessionId);
+}
+/** The live state, created on first write. Reads must not create entries. */
+function stateForWrite(sessionId) {
+    let state = checklists.get(sessionId);
+    if (!state) {
+        state = { sessionId, items: [], updatedAt: Date.now() };
+        checklists.set(sessionId, state);
+    }
+    return state;
+}
+/** Continue the id run rather than reusing an id a closed item still holds. */
+function nextItemId(items) {
+    let highest = 0;
+    for (const item of items) {
+        const parsed = Number.parseInt(item.id.slice(ID_PREFIX.length), 10);
+        if (Number.isFinite(parsed) && parsed > highest) {
+            highest = parsed;
+        }
+    }
+    return `${ID_PREFIX}${highest + 1}`;
+}
+function toResult(state) {
+    const counts = {
+        pending: 0,
+        in_progress: 0,
+        done: 0,
+        closed: 0,
+    };
+    for (const item of state.items) {
+        counts[item.status] += 1;
+    }
+    const delegates = delegateCountsFor(state.sessionId);
+    const runCommands = commandCountsFor(state.sessionId);
+    return {
+        items: state.items.map((item) => ({ ...item })),
+        counts,
+        delegatesPending: delegates.pending,
+        delegatesReady: delegates.ready,
+        commandsRunning: runCommands.running,
+        commandsFinished: runCommands.finished,
+    };
+}
+/** Matches `agentToolRegistrar`'s convention: the recovery step is IN the text. */
+function refusal(message) {
+    return { isError: true, error: message };
+}
+const CREATE_SCHEMA = z.object({
+    titles: z
+        .array(z.string())
+        .describe("One short imperative title per task, in the order you intend to work them, " +
+        'e.g. ["Check auth changes against the security rules", "Review the migration files"].'),
+});
+const UPDATE_SCHEMA = z.object({
+    id: z.string().describe('Task id from the checklist, e.g. "t2".'),
+    status: z
+        .enum(["pending", "in_progress", "done", "closed"])
+        .describe("in_progress when you start it, done when it is finished, closed when it " +
+        "will NOT be done (a reason is then required)."),
+    note: z
+        .string()
+        .optional()
+        .describe("What you found, or — for closed — why the task will not be done. Required for closed."),
+});
+const LIST_SCHEMA = z.object({});
+/**
+ * The three model-facing checklist tools, bound to `host` for session
+ * resolution. Register them with `host.registerTool()` (see
+ * `NeuroLink.registerTaskTools()`), never on the tool registry directly:
+ * only the "user-defined" category reaches the LLM's tool schema.
+ */
+export function createChecklistTools(host) {
+    return {
+        tasks_create: {
+            name: "tasks_create",
+            description: "Write the checklist of concrete tasks this run must finish. Call it once " +
+                "up front, and again only to ADD tasks you discover later — titles are " +
+                "appended, never replaced, and the engine assigns the ids. Returns the full " +
+                "checklist. Pending tasks mean the work is not finished.",
+            inputSchema: CREATE_SCHEMA,
+            execute: async (params, context) => {
+                const parsed = CREATE_SCHEMA.safeParse(params ?? {});
+                if (!parsed.success) {
+                    return refusal("tasks_create expects { titles: string[] }. Call it again with a non-empty " +
+                        "array of short task titles.");
+                }
+                const titles = parsed.data.titles
+                    .map((title) => title.trim())
+                    .filter((title) => title.length > 0);
+                if (titles.length === 0) {
+                    return refusal("No task titles were given. Call tasks_create again with at least one " +
+                        "non-empty title describing work this run must finish.");
+                }
+                const sessionId = resolveChecklistSessionId(host, context);
+                const state = stateForWrite(sessionId);
+                const now = Date.now();
+                for (const title of titles) {
+                    state.items.push({
+                        id: nextItemId(state.items),
+                        title,
+                        status: "pending",
+                        createdAt: now,
+                        updatedAt: now,
+                    });
+                }
+                state.updatedAt = now;
+                logger.debug("[TaskChecklist] Items created", {
+                    sessionId,
+                    added: titles.length,
+                    total: state.items.length,
+                });
+                return toResult(state);
+            },
+        },
+        tasks_update: {
+            name: "tasks_update",
+            description: "Move one checklist task to a new status: in_progress when you start it, " +
+                "done when it is genuinely finished, closed when it will not be done (say " +
+                "why in note — a closed task without a reason is refused). Returns the full " +
+                "checklist so you always see what is left.",
+            inputSchema: UPDATE_SCHEMA,
+            execute: async (params, context) => {
+                const parsed = UPDATE_SCHEMA.safeParse(params ?? {});
+                if (!parsed.success) {
+                    return refusal(`tasks_update expects { id, status, note? } with status one of ${STATUSES.join(" | ")}. Call tasks_list to see the current ids, then retry.`);
+                }
+                const { id, status, note } = parsed.data;
+                const sessionId = resolveChecklistSessionId(host, context);
+                const state = checklists.get(sessionId);
+                const item = state?.items.find((candidate) => candidate.id === id);
+                if (!state || !item) {
+                    const valid = state?.items.map((candidate) => candidate.id) ?? [];
+                    return refusal(valid.length > 0
+                        ? `No checklist task "${id}". Valid ids are ${valid.join(", ")} — retry with one of them.`
+                        : `No checklist task "${id}": the checklist is empty. Call tasks_create first.`);
+                }
+                const reason = note?.trim();
+                if (status === "closed" && !reason) {
+                    return refusal(`Closing "${id}" needs a reason. Call tasks_update again with note set to why ` +
+                        "this task will not be completed, or finish it and mark it done.");
+                }
+                item.status = status;
+                if (reason) {
+                    item.note = reason;
+                }
+                item.updatedAt = Date.now();
+                state.updatedAt = item.updatedAt;
+                logger.debug("[TaskChecklist] Item updated", {
+                    sessionId,
+                    id,
+                    status,
+                });
+                return toResult(state);
+            },
+        },
+        tasks_list: {
+            name: "tasks_list",
+            description: "Read the current checklist — every task with its status, plus how many " +
+                "background workers are still running or waiting to be collected and how many " +
+                "background commands are still running or have finished unread. Use it to " +
+                "re-orient after a long stretch of work; it is cheap and always current.",
+            inputSchema: LIST_SCHEMA,
+            execute: async (_params, context) => {
+                const sessionId = resolveChecklistSessionId(host, context);
+                return toResult(checklists.get(sessionId) ?? emptyState(sessionId));
+            },
+        },
+    };
+}

package/dist/artifacts/artifactBanking.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Artifact banking (N3) — bank the whole payload, hand back a pointer.
+ *
+ * A long-running agent produces outputs that do not fit in a conversation:
+ * a worker's full report, a build log, a stage's structured result. The wrong
+ * answer is to truncate one and send the head — the discarded bytes are gone
+ * and nothing records that they existed. The right answer is to write the
+ * payload to disk in full and put a bounded preview plus a read-back call in
+ * the conversation, so the model can pull as much of the rest as it needs,
+ * whenever it needs it, and compaction can evict the preview without costing
+ * anything.
+ *
+ * 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.
+ *
+ * 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,
+ * and `retrieve_context` is registered along with it.
+ *
+ * @module artifacts/artifactBanking
+ */
+import type { NeuroLink } from "../neurolink.js";
+import type { ArtifactPageRequest, ArtifactStore, BankArtifactOptions, BankedArtifactRef } from "../types/index.js";
+/**
+ * The artifact store for this instance, created on first use.
+ *
+ * Lazy creation lives on the host rather than here because both pieces of it
+ * are private to `NeuroLink`: the store field the `retrieve_context` closure
+ * reads, and the registration of that tool. Calling it through the host is
+ * what makes a banked artifact readable by the model, not just by host code.
+ */
+export declare function ensureArtifactStore(host: NeuroLink): ArtifactStore;
+/**
+ * Write a payload to the artifact store and return a reference to it.
+ *
+ * The payload is stored whole. The returned `preview` is a bounded head slice
+ * for the conversation, and `readBackHint` is the call that fetches the rest.
+ *
+ * @param host     Instance whose artifact store (and `retrieve_context`) to use.
+ * @param payload  The complete text or JSON payload. Never truncated.
+ * @param options  What this is (`kind` / `label`) and how big a preview to cut.
+ */
+export declare function bankArtifact(host: NeuroLink, payload: string, options: BankArtifactOptions): Promise<BankedArtifactRef>;
+/**
+ * Read a banked payload back from host code — the programmatic twin of the
+ * `retrieve_context` tool the model uses.
+ *
+ * Returns the FULL payload when `page` is omitted; there is no hidden cap,
+ * 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.
+ *
+ * @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

@@ -0,0 +1,123 @@
+/**
+ * Artifact banking (N3) — bank the whole payload, hand back a pointer.
+ *
+ * A long-running agent produces outputs that do not fit in a conversation:
+ * a worker's full report, a build log, a stage's structured result. The wrong
+ * answer is to truncate one and send the head — the discarded bytes are gone
+ * and nothing records that they existed. The right answer is to write the
+ * payload to disk in full and put a bounded preview plus a read-back call in
+ * the conversation, so the model can pull as much of the rest as it needs,
+ * whenever it needs it, and compaction can evict the preview without costing
+ * anything.
+ *
+ * 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.
+ *
+ * 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,
+ * and `retrieve_context` is registered along with it.
+ *
+ * @module artifacts/artifactBanking
+ */
+/** Preview length when the caller does not ask for one. */
+const DEFAULT_BANK_PREVIEW_CHARS = 1000;
+/**
+ * Ceiling on a preview, however much the caller asks for. A preview is a
+ * pointer into the banked file; past a few thousand characters it stops being
+ * a pointer and starts being the context pressure banking exists to remove.
+ */
+const MAX_BANK_PREVIEW_CHARS = 4000;
+/** `serverId` recorded on banked artifacts — distinguishes them from MCP surrogates. */
+const BANK_SERVER_ID = "neurolink-banking";
+/** Chunk size suggested in the read-back hint (matches retrieve_context's default). */
+const READ_BACK_CHUNK_CHARS = 50_000;
+/**
+ * The artifact store for this instance, created on first use.
+ *
+ * Lazy creation lives on the host rather than here because both pieces of it
+ * are private to `NeuroLink`: the store field the `retrieve_context` closure
+ * reads, and the registration of that tool. Calling it through the host is
+ * what makes a banked artifact readable by the model, not just by host code.
+ */
+export function ensureArtifactStore(host) {
+    return host.getArtifactStore();
+}
+/** Head slice of the payload, clamped to the caller's budget and the ceiling. */
+function boundedPreview(payload, requested) {
+    const chars = Math.min(Math.max(0, requested ?? DEFAULT_BANK_PREVIEW_CHARS), MAX_BANK_PREVIEW_CHARS);
+    return payload.length <= chars ? payload : `${payload.slice(0, chars)}…`;
+}
+/**
+ * The literal call that reads the payload back.
+ *
+ * Spelled out rather than described: a model that is handed a preview and the
+ * exact next call does not have to guess a tool name, an argument name, or
+ * how to page — and the sentence says outright that nothing was discarded, so
+ * "the rest is not worth asking for" is never a reasonable inference.
+ */
+function readBackHintFor(id, sizeBytes) {
+    return (`retrieve_context({ artifactId: "${id}", offset: 0, limit: ${READ_BACK_CHUNK_CHARS} }) ` +
+        `— the complete ${sizeBytes}-byte payload is stored; nothing was discarded. ` +
+        `Repeat with offset advanced by the characters you received while hasMore is true.`);
+}
+/**
+ * Write a payload to the artifact store and return a reference to it.
+ *
+ * The payload is stored whole. The returned `preview` is a bounded head slice
+ * for the conversation, and `readBackHint` is the call that fetches the rest.
+ *
+ * @param host     Instance whose artifact store (and `retrieve_context`) to use.
+ * @param payload  The complete text or JSON payload. Never truncated.
+ * @param options  What this is (`kind` / `label`) and how big a preview to cut.
+ */
+export async function bankArtifact(host, payload, options) {
+    const store = ensureArtifactStore(host);
+    const label = options.label.trim() || options.kind;
+    const contentType = options.contentType ?? "text";
+    const sizeBytes = Buffer.byteLength(payload, "utf-8");
+    const ref = await store.store(payload, {
+        toolName: `bank:${options.kind}`,
+        serverId: BANK_SERVER_ID,
+        sessionId: options.sessionId,
+        sizeBytes,
+        contentType,
+        label,
+        kind: options.kind,
+    });
+    return {
+        artifactId: ref.id,
+        label,
+        kind: options.kind,
+        sizeBytes,
+        preview: boundedPreview(payload, options.previewChars),
+        readBackHint: readBackHintFor(ref.id, sizeBytes),
+    };
+}
+/**
+ * Read a banked payload back from host code — the programmatic twin of the
+ * `retrieve_context` tool the model uses.
+ *
+ * Returns the FULL payload when `page` is omitted; there is no hidden cap,
+ * 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.
+ *
+ * @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));
+}

package/dist/artifacts/artifactStore.d.ts

@@ -22,13 +22,11 @@ import type { ArtifactMeta, ArtifactRef, ArtifactStore } from "../types/index.js
  * Filesystem-backed artifact store using the OS temp directory.
  *
  * Files are written with mode 0o600 (owner read/write only).
- * An in-memory index tracks metadata without a separate index file.
- *
- * Suitable for:
- *  - CLI usage
- *  - Single-process SDK deployments
- *  - Multi-process deployments where each process manages its own artifacts
- *    (artifacts created in one process are not visible to others)
+ * An in-memory index tracks metadata for the fast path; every payload also
+ * gets a `<id>.meta.json` sidecar, so an id this process never stored — from
+ * another process, or from before a restart — still resolves (see
+ * `rehydrate`). `cleanup()` remains index-scoped: it expires what this process
+ * knows about, and never walks the directory deleting another process's work.
  *
  * @example
  * ```typescript
@@ -46,10 +44,40 @@ import type { ArtifactMeta, ArtifactRef, ArtifactStore } from "../types/index.js
 export declare class LocalTempArtifactStore implements ArtifactStore {
     private readonly dir;
     private readonly index;
-    constructor(dir?: string);
+    private readonly rehydrateFromDisk;
+    /**
+     * @param dir - Storage directory; defaults to `tmpdir()/neurolink-artifacts`
+     * @param options - `rehydrateFromDisk` (default true) lets `retrieve()` and
+     *   `delete()` fall back to the on-disk sidecar index on an in-memory miss,
+     *   which makes artifacts READABLE AND DELETABLE ACROSS PROCESSES sharing
+     *   the same directory and unix user. Pass `false` — or set
+     *   `NEUROLINK_ARTIFACT_REHYDRATE=false` — to restore strict per-process
+     *   isolation: ids not stored by this process resolve to nothing.
+     */
+    constructor(dir?: string, options?: {
+        rehydrateFromDisk?: boolean;
+    });
     generatePreview(payload: string): string;
     store(payload: string, meta: Omit<ArtifactMeta, "createdAt">): Promise<ArtifactRef>;
     retrieve(id: string): Promise<string | null>;
     delete(id: string): Promise<void>;
     cleanup(olderThanMs: number): Promise<number>;
+    /**
+     * Record the index row next to the payload.
+     *
+     * The index is per-process, so without this an artifact written by one
+     * process is invisible to every other one — and to the same process after a
+     * restart. A failed sidecar write is logged, never fatal: the payload is
+     * already safely on disk and this process can still read it from its index.
+     */
+    private writeSidecar;
+    /**
+     * Resolve an id the in-memory index does not know: another process stored
+     * it, or this process restarted. Reads the sidecar first (full metadata);
+     * 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.
+     */
+    private rehydrate;
 }