const log = createSubsystemLogger("memory");

/**

* Normalize an already-aborted search signal into the error thrown before any

* qmd work starts. Prefers the caller-supplied abort reason (so a deadline

* message such as "memory_search timed out after 15s" survives) and falls back

* to a stable abort error.

*/

function asAbortError(signal: AbortSignal): Error {

const reason = signal.reason;

if (reason instanceof Error) {

return reason;

}

if (typeof reason === "string" && reason.length > 0) {

return new Error(reason);

}

return new Error("qmd search aborted");

}

const SNIPPET_HEADER_RE = /@@\s*-([0-9]+),([0-9]+)/;

const SEARCH_PENDING_UPDATE_WAIT_MS = 500;

const MAX_QMD_OUTPUT_CHARS = 200_000;

qmdSearchModeOverride?: "query" | "search" | "vsearch";

onDebug?: (debug: MemorySearchRuntimeDebug) => void;

sources?: MemorySource[];

/**

* Caller-owned cancellation. When the caller stops waiting (e.g. the

* memory_search tool deadline fires), abort kills the in-flight qmd

* subprocess instead of leaving it running orphaned for the full qmd

* timeout.

*/

signal?: AbortSignal;

},

): Promise<MemorySearchResult[]> {

if (!this.isScopeAllowed(opts?.sessionKey)) {

this.logScopeDenied(opts?.sessionKey);

return [];

}

const searchSignal = opts?.signal;

if (searchSignal?.aborted) {

throw asAbortError(searchSignal);

}

const trimmed = query.trim();

if (!trimmed) {

return [];

}

const args = this.buildSearchArgs(qmdSearchCommand, trimmed, limit);

args.push(...this.buildCollectionFilterArgs(collectionGroups[0] ?? collectionNames));

return await this.runQmdSearch(args, qmdSearchCommand);

return await this.runQmdSearch(args, qmdSearchCommand, searchSignal);

} catch (err) {

if (allowMissingCollectionRepair && this.isMissingCollectionSearchError(err)) {

throw err;

fallbackArgs.push(

...this.buildCollectionFilterArgs(collectionGroups[0] ?? collectionNames),

);

return await this.runQmdSearch(fallbackArgs, "query");

return await this.runQmdSearch(fallbackArgs, "query", searchSignal);

} catch (fallbackErr) {

log.warn(`qmd query fallback failed: ${String(fallbackErr)}`);

throw fallbackErr instanceof Error ? fallbackErr : new Error(String(fallbackErr));

private async runQmd(

args: string[],

opts?: { timeoutMs?: number; discardOutput?: boolean },

opts?: { timeoutMs?: number; discardOutput?: boolean; signal?: AbortSignal },

): Promise<{ stdout: string; stderr: string }> {

return await runCliCommand({

commandSummary: `qmd ${args.join(" ")}`,

maxOutputChars: this.maxQmdOutputChars,

// Large `qmd update` runs can easily exceed the output cap; keep only stderr.

discardStdout: opts?.discardOutput,

signal: opts?.signal,

});

}

private async runQmdSearch(

args: string[],

command: "query" | "search" | "vsearch",

signal?: AbortSignal,

): Promise<QmdQueryResult[]> {

try {

const result = await this.runQmd(args, { timeoutMs: this.qmd.limits.timeoutMs });

const result = await this.runQmd(args, { timeoutMs: this.qmd.limits.timeoutMs, signal });

return parseQmdQueryJson(result.stdout, result.stderr);

} catch (err) {

const recovered = this.parseFailedQmdSearchJson(err, command);