@gpzhang2001/sharpkit-analysis 0.2.1

package/lib/index.js

@@ -0,0 +1,1231 @@
+import { dirname, join } from "node:path";
+import { defineTool } from "@deepseek-ai/dsh-tools";
+import { mkdir, readFile, rename, writeFile } from "node:fs/promises";
+//#region src/stores.ts
+/**
+* Run-scoped JSON mirror stores (strix .state/ mirrors): atomic writes
+* (temp-in-dir + rename), hydrate-on-start, per-store in-memory maps.
+* One instance per scan, owned by the analysis service.
+* @module @gpzhang2001/sharpkit-analysis/stores
+*/
+/** A JSON file mirror with atomic write and hydrate. */
+var JsonMirrorStore = class {
+	path;
+	map = /* @__PURE__ */ new Map();
+	constructor(path) {
+		this.path = path;
+	}
+	/** Load the mirror file; corrupt JSON is tolerated as empty on hydrate (resume aid only). */
+	async hydrate() {
+		if (this.path === null) return;
+		try {
+			const raw = await readFile(this.path, "utf8");
+			const parsed = JSON.parse(raw);
+			if (typeof parsed !== "object" || parsed === null) return;
+			for (const [key, value] of Object.entries(parsed)) if (typeof value === "object" && value !== null) this.map.set(key, value);
+		} catch {}
+	}
+	/** Persist the whole map atomically (strix `_persist_locked`). */
+	async persist() {
+		if (this.path === null) return;
+		const payload = JSON.stringify(Object.fromEntries(this.map), null, 2);
+		await mkdir(dirname(this.path), { recursive: true });
+		const temp = `${dirname(this.path)}/.${join("", this.path.split("/").pop() ?? "store")}.${process.pid}.tmp`;
+		await writeFile(temp, payload, "utf8");
+		await rename(temp, this.path);
+	}
+	get(key) {
+		return this.map.get(key);
+	}
+	set(key, value) {
+		this.map.set(key, value);
+	}
+	delete(key) {
+		return this.map.delete(key);
+	}
+	values() {
+		return [...this.map.values()];
+	}
+	get size() {
+		return this.map.size;
+	}
+};
+/** Generate a 6-hex id with bounded collision retries (strix parity). */
+function generateId(existing) {
+	for (let attempt = 0; attempt < 1024; attempt++) {
+		const id = Math.random().toString(16).slice(2, 8).padEnd(6, "0");
+		if (!existing.has(id)) return id;
+	}
+	return null;
+}
+/**
+* Normalize a remote target to its identity (threat_model/tools.py
+* `_normalize_remote_target` + `_normalize_git_remote`): scp-style and
+* scheme'd git remotes map to https URLs, `.git` stripped, trailing slash
+* stripped, host lowercased with default ports collapsed.
+* @param target - the raw target string.
+*/
+function normalizeTargetIdentity(target) {
+	const trimmed = target.trim();
+	const scp = /^git@([^:]+):(.+?)(?:\.git)?$/.exec(trimmed);
+	if (scp !== null) return `https://${scp[1]?.toLowerCase()}/${scp[2]}`;
+	const withScheme = /^([a-z][a-z0-9+.-]*):\/\/([^/?#]+)([^#]*)/i.exec(trimmed);
+	if (withScheme !== null) {
+		const scheme = withScheme[1] ?? "";
+		const authority = withScheme[2] ?? "";
+		const path = withScheme[3] ?? "";
+		const defaultPort = scheme.toLowerCase() === "https" ? "443" : scheme.toLowerCase() === "http" ? "80" : null;
+		let host = authority.toLowerCase();
+		if (defaultPort !== null && host.endsWith(`:${defaultPort}`)) host = host.slice(0, -defaultPort.length - 1);
+		return `https://${host}${path.replace(/\/$/, "")}`.replace(/\.git$/, "");
+	}
+	return trimmed.replace(/\/$/, "").replace(/\.git$/, "");
+}
+//#endregion
+//#region src/index.ts
+/**
+* Analysis tools — port of strix tools/{threat_model,coverage,notes,
+* thinking}/ + finish_scan: get/save/amend_threat_model (validated
+* sections, size gates, append-only amendments), record/update/
+* list_coverage (duplicate guard, evidence requirements, history),
+* create/list/get/update/delete_note, think, and finish_scan (root-only,
+* four required sections, coverage summary, final artifacts). State lives
+* in per-scan mirror stores under the run dir (.state parity) and is
+* provided as `pentestAnalysis` for the reporting package's coverage
+* document and SARIF bridge.
+* @module @gpzhang2001/sharpkit-analysis
+*/
+/** Coverage outcome values (strix VALID_OUTCOMES). */
+const VALID_OUTCOMES = [
+	"reported",
+	"no_issue_found",
+	"ruled_out",
+	"not_applicable",
+	"needs_follow_up"
+];
+/** Outcomes that require evidence text (strix `_OUTCOMES_REQUIRING_EVIDENCE`). */
+const OUTCOMES_REQUIRING_EVIDENCE = /* @__PURE__ */ new Set([
+	"ruled_out",
+	"not_applicable",
+	"needs_follow_up"
+]);
+/** Note categories (strix `_VALID_NOTE_CATEGORIES`). */
+const VALID_NOTE_CATEGORIES = [
+	"general",
+	"findings",
+	"methodology",
+	"questions",
+	"plan",
+	"wiki"
+];
+/** Required threat-model sections, matched as lowercase substrings (strix parity). */
+const REQUIRED_SECTIONS = [
+	"overview",
+	"trust boundaries",
+	"attack surface",
+	"severity calibration"
+];
+/** Threat model gates (strix constants). */
+const MAX_MODEL_BYTES = 524288;
+const MIN_MODEL_CHARS = 400;
+const MIN_AMENDMENT_CHARS = 80;
+const MAX_AMENDMENTS = 40;
+/** Display timestamp in the coverage format. */
+function displayTimestamp(date) {
+	const pad = (value) => String(value).padStart(2, "0");
+	return `${date.getUTCFullYear()}-${pad(date.getUTCMonth() + 1)}-${pad(date.getUTCDate())} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} UTC`;
+}
+const name = "pentest-tool-analysis";
+const inject = ["tools", "pentestReporting"];
+/** ISO-8601 timestamp (threat model + notes stores). */
+function isoNow() {
+	return (/* @__PURE__ */ new Date()).toISOString().replace("Z", "+00:00");
+}
+function apply(ctx, config = {}) {
+	const scanId = config.scanId ?? "pentest";
+	const runDir = config.runDir ?? join("sharpkit_runs", scanId);
+	const stateDir = join(runDir, ".state");
+	const coverage = new JsonMirrorStore(join(stateDir, "coverage.json"));
+	const threatModels = new JsonMirrorStore(join(stateDir, "threat_models.json"));
+	const notes = new JsonMirrorStore(join(stateDir, "notes.json"));
+	coverage.hydrate();
+	threatModels.hydrate();
+	notes.hydrate();
+	const coverageEntries = () => coverage.values().map((entry) => ({
+		...entry,
+		entry_id: String(entry["id"] ?? "")
+	}));
+	const outcomeCounts = () => {
+		const counts = {};
+		for (const outcome of VALID_OUTCOMES) {
+			const count = coverage.values().filter((entry) => entry["outcome"] === outcome).length;
+			if (count > 0) counts[outcome] = count;
+		}
+		return counts;
+	};
+	const handle = {
+		coverage,
+		threatModels,
+		notes,
+		coverageEntries,
+		outcomeCounts
+	};
+	ctx.provide("pentestAnalysis", handle);
+	const resolveTarget = (target) => {
+		const cleaned = target?.trim() ?? "";
+		if (cleaned === "") {
+			const targets = config.scanTargets ?? [];
+			if (targets.length === 1) return { identity: normalizeTargetIdentity(targets[0] ?? "") };
+			return { error: "target cannot be empty - name the target this threat model describes" };
+		}
+		return { identity: normalizeTargetIdentity(cleaned) };
+	};
+	ctx.tools.register(defineTool({
+		name: "get_threat_model",
+		description: "Fetch the threat model shared for a target in this scan (found=false when none exists yet). Read-only.",
+		parameters: { target: {
+			type: "string",
+			description: "Target the model describes; omit when the scan has exactly one target."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					found: { type: "boolean" },
+					target: { type: "string" },
+					content: { type: "string" },
+					amendments: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {},
+							additionalProperties: true
+						}
+					},
+					amendments_note: { type: "string" },
+					message: { type: "string" },
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				if (!result.success) return [{
+					type: "text",
+					text: `get_threat_model failed: ${result.error ?? "unknown"}`
+				}];
+				return [{
+					type: "text",
+					text: result.found === true ? "threat model found" : "no threat model yet"
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const resolved = resolveTarget(rawArgs.target);
+			if ("error" in resolved) return {
+				success: false,
+				error: resolved.error
+			};
+			const model = threatModels.get(resolved.identity);
+			if (model === void 0 || String(model["content"] ?? "").trim() === "") return {
+				success: true,
+				found: false,
+				target: resolved.identity,
+				message: "No threat model exists for this target yet. Save one with save_threat_model."
+			};
+			const amendments = model["amendments"];
+			return {
+				success: true,
+				found: true,
+				target: resolved.identity,
+				content: String(model["content"]),
+				...amendments !== void 0 && amendments.length > 0 ? {
+					amendments,
+					amendments_note: "Addenda recorded by agents after the model was saved."
+				} : {}
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "save_threat_model",
+		description: `Share your threat model for a target with the whole scan team (full replace; clears amendments). Must cover Overview, Trust Boundaries, Attack Surface, and Severity Calibration; minimum ${String(MIN_MODEL_CHARS)} characters, maximum 512KB.`,
+		parameters: {
+			target: {
+				type: "string",
+				description: "Target the model describes; omit when the scan has exactly one target."
+			},
+			content: {
+				type: "string",
+				required: true,
+				description: "The full markdown threat model."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					target: { type: "string" },
+					amendments_cleared: { type: "integer" },
+					message: { type: "string" },
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				return [{
+					type: "text",
+					text: result.success ? "threat model saved" : `save_threat_model failed: ${result.error ?? "unknown"}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			const resolved = resolveTarget(args.target);
+			if ("error" in resolved) return {
+				success: false,
+				error: resolved.error
+			};
+			const content = args.content.trim();
+			if (content.length < MIN_MODEL_CHARS) return {
+				success: false,
+				error: `Threat model is too thin (${String(content.length)} chars). It has to be usable by every agent in this scan.`
+			};
+			if (Buffer.byteLength(content, "utf8") > MAX_MODEL_BYTES) return {
+				success: false,
+				error: "Threat model exceeds 512KB; tighten it."
+			};
+			const lower = content.toLowerCase();
+			const missing = REQUIRED_SECTIONS.filter((section) => !lower.includes(section));
+			if (missing.length > 0) return {
+				success: false,
+				error: `Threat model is missing required section(s): ${missing.join(", ")}. Cover Overview, Trust Boundaries, Attack Surface, and Severity Calibration.`
+			};
+			const previousAmendments = threatModels.get(resolved.identity)?.["amendments"];
+			const amendmentsCleared = Array.isArray(previousAmendments) ? previousAmendments.length : 0;
+			threatModels.set(resolved.identity, {
+				target: resolved.identity,
+				written_at: isoNow(),
+				written_by: null,
+				content
+			});
+			await threatModels.persist();
+			return {
+				success: true,
+				target: resolved.identity,
+				amendments_cleared: amendmentsCleared,
+				message: amendmentsCleared > 0 ? `Threat model shared with this scan. It replaced a previous model, folding ${String(amendmentsCleared)} amendment(s) into the full rewrite.` : "Threat model shared with this scan."
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "amend_threat_model",
+		description: `Append an addendum to the existing threat model without rewriting it (minimum ${String(MIN_AMENDMENT_CHARS)} characters). Use save_threat_model for a full rewrite that folds amendments.`,
+		parameters: {
+			target: {
+				type: "string",
+				description: "Target the model describes; omit when the scan has exactly one target."
+			},
+			addendum: {
+				type: "string",
+				required: true,
+				description: "The markdown addendum."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					target: { type: "string" },
+					amendment_count: { type: "integer" },
+					message: { type: "string" },
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				return [{
+					type: "text",
+					text: result.success ? "amendment recorded" : `amend_threat_model failed: ${result.error ?? "unknown"}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			const resolved = resolveTarget(args.target);
+			if ("error" in resolved) return {
+				success: false,
+				error: resolved.error
+			};
+			const addendum = args.addendum.trim();
+			if (addendum.length < MIN_AMENDMENT_CHARS) return {
+				success: false,
+				error: `Amendment is too thin (${String(addendum.length)} chars). Give the new knowledge in full.`
+			};
+			const model = threatModels.get(resolved.identity);
+			if (model === void 0) return {
+				success: false,
+				error: "No threat model exists for this target yet. Save the full model with save_threat_model first."
+			};
+			const amendments = model["amendments"] ?? [];
+			if (amendments.length >= MAX_AMENDMENTS) return {
+				success: false,
+				error: `This threat model already carries ${String(amendments.length)} amendments. Fold them into a full save_threat_model rewrite.`
+			};
+			if (Buffer.byteLength(String(model["content"]) + addendum, "utf8") > MAX_MODEL_BYTES) return {
+				success: false,
+				error: "Combined threat model exceeds 512KB; fold amendments with save_threat_model."
+			};
+			amendments.push({
+				at: isoNow(),
+				by: null,
+				content: addendum
+			});
+			model["amendments"] = amendments;
+			await threatModels.persist();
+			return {
+				success: true,
+				target: resolved.identity,
+				amendment_count: amendments.length,
+				message: "Amendment recorded. Every agent reading the threat model will see it."
+			};
+		})
+	}));
+	/** strix coverage `_validate`: normalization + per-field errors. */
+	function validateCoverage(input) {
+		const errors = [];
+		if (input.surface === "") errors.push("surface cannot be empty - name the endpoint, route, file, or component");
+		if (input.riskArea === "") errors.push("risk_area cannot be empty - name what you were testing for");
+		const outcome = input.outcome.trim().toLowerCase().replaceAll("-", "_").replaceAll(" ", "_");
+		if (!VALID_OUTCOMES.includes(outcome)) errors.push(`Invalid outcome: '${input.outcome}'. Must be one of: [${VALID_OUTCOMES.join(", ")}]`);
+		if (OUTCOMES_REQUIRING_EVIDENCE.has(outcome) && input.evidence === "") errors.push(`evidence is required for outcome '${outcome}' - name the specific control, response, or observation that justifies it`);
+		return errors.length > 0 ? { errors } : { outcome };
+	}
+	const findCoverageDuplicate = (surface, riskArea) => coverage.values().find((entry) => String(entry["surface"]).toLowerCase() === surface.toLowerCase() && String(entry["risk_area"]).toLowerCase() === riskArea.toLowerCase());
+	ctx.tools.register(defineTool({
+		name: "record_coverage",
+		description: "Record that you exercised an attack surface for a risk area, with an outcome. Outcomes: reported / no_issue_found / ruled_out / not_applicable / needs_follow_up. ruled_out, not_applicable, and needs_follow_up REQUIRE evidence. One entry per (surface, risk_area).",
+		parameters: {
+			surface: {
+				type: "string",
+				required: true,
+				description: "The endpoint, route, file, or component you exercised."
+			},
+			risk_area: {
+				type: "string",
+				required: true,
+				description: "What you were testing for (e.g. \"SQL injection in login\")."
+			},
+			outcome: {
+				type: "string",
+				required: true,
+				enum: [...VALID_OUTCOMES],
+				description: "The testing outcome."
+			},
+			evidence: {
+				type: "string",
+				description: "Concrete observation justifying the outcome (required for some outcomes)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					entry_id: { type: "string" },
+					outcome: { type: "string" },
+					message: { type: "string" },
+					error: { type: "string" },
+					errors: {
+						type: "array",
+						items: { type: "string" }
+					},
+					existing_entry_id: { type: "string" },
+					existing_outcome: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				const reason = result.error ?? result.errors?.join("; ") ?? "unknown";
+				return [{
+					type: "text",
+					text: result.success ? "coverage recorded" : `record_coverage failed: ${reason}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			const surface = (args.surface ?? "").trim();
+			const riskArea = (args.risk_area ?? "").trim();
+			const evidence = (args.evidence ?? "").trim();
+			const checked = validateCoverage({
+				surface,
+				riskArea,
+				outcome: args.outcome ?? "",
+				evidence
+			});
+			if ("errors" in checked) return {
+				success: false,
+				error: "Validation failed",
+				errors: checked.errors
+			};
+			const duplicate = findCoverageDuplicate(surface, riskArea);
+			if (duplicate !== void 0) return {
+				success: false,
+				error: `'${surface}' (${riskArea}) already has coverage entry ${String(duplicate["id"])}, recorded by ${String(duplicate["agent_name"] ?? "an agent")} as '${String(duplicate["outcome"])}'. Two rows for the same surface and risk area are never allowed; update_coverage to change the outcome.`,
+				existing_entry_id: String(duplicate["id"]),
+				existing_outcome: String(duplicate["outcome"])
+			};
+			const id = generateId(new Set(coverage.values().map((entry) => String(entry["id"] ?? ""))));
+			if (id === null) return {
+				success: false,
+				error: "could not allocate a coverage entry id"
+			};
+			coverage.set(id, {
+				id,
+				surface,
+				risk_area: riskArea,
+				outcome: checked.outcome,
+				created_at: displayTimestamp(/* @__PURE__ */ new Date()),
+				...evidence !== "" ? { evidence } : {}
+			});
+			await coverage.persist();
+			return {
+				success: true,
+				entry_id: id,
+				outcome: checked.outcome,
+				message: `Coverage recorded for '${surface}' (${checked.outcome})`
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "update_coverage",
+		description: "Move an existing coverage entry to a new outcome (surface and risk_area are never editable). The previous state is kept as history.",
+		parameters: {
+			entry_id: {
+				type: "string",
+				required: true,
+				description: "Id from record_coverage or list_coverage."
+			},
+			outcome: {
+				type: "string",
+				required: true,
+				enum: [...VALID_OUTCOMES],
+				description: "The new outcome."
+			},
+			evidence: {
+				type: "string",
+				description: "Evidence for the new outcome (required for some outcomes)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					entry_id: { type: "string" },
+					previous_outcome: { type: "string" },
+					outcome: { type: "string" },
+					message: { type: "string" },
+					error: { type: "string" },
+					errors: {
+						type: "array",
+						items: { type: "string" }
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				const reason = result.error ?? result.errors?.join("; ") ?? "unknown";
+				return [{
+					type: "text",
+					text: result.success ? "coverage updated" : `update_coverage failed: ${reason}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			const entryId = (args.entry_id ?? "").trim();
+			const entry = coverage.get(entryId);
+			if (entry === void 0) return {
+				success: false,
+				error: `No coverage entry '${entryId}'. Call list_coverage to see recorded entries.`
+			};
+			const surface = String(entry["surface"] ?? "");
+			const riskArea = String(entry["risk_area"] ?? "");
+			const evidence = (args.evidence ?? "").trim();
+			const checked = validateCoverage({
+				surface,
+				riskArea,
+				outcome: args.outcome ?? "",
+				evidence
+			});
+			if ("errors" in checked) return {
+				success: false,
+				error: "Validation failed",
+				errors: checked.errors
+			};
+			const previousOutcome = String(entry["outcome"]);
+			const history = entry["history"] ?? [];
+			const prior = {
+				outcome: previousOutcome,
+				recorded_at: String(entry["created_at"])
+			};
+			if (entry["evidence"] !== void 0) prior["evidence"] = entry["evidence"];
+			history.push(prior);
+			entry["history"] = history;
+			entry["outcome"] = checked.outcome;
+			entry["updated_at"] = displayTimestamp(/* @__PURE__ */ new Date());
+			if (evidence !== "") entry["evidence"] = evidence;
+			await coverage.persist();
+			return {
+				success: true,
+				entry_id: entryId,
+				previous_outcome: previousOutcome,
+				outcome: checked.outcome,
+				message: `'${surface}' (${riskArea}) moved from ${previousOutcome} to ${checked.outcome}. The previous state is kept as history.`
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "list_coverage",
+		description: "List coverage entries recorded in this scan (filters compose; outcome counts are over all entries).",
+		parameters: {
+			outcome: {
+				type: "string",
+				description: "Filter to one outcome."
+			},
+			surface: {
+				type: "string",
+				description: "Case-insensitive substring match on the surface."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					entries: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {},
+							additionalProperties: true
+						},
+						required: true
+					},
+					filtered_count: {
+						type: "integer",
+						required: true
+					},
+					total_count: {
+						type: "integer",
+						required: true
+					},
+					outcome_counts: {
+						type: "object",
+						properties: {},
+						additionalProperties: true,
+						required: true
+					},
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				if (result.error !== void 0) return [{
+					type: "text",
+					text: `list_coverage failed: ${result.error}`
+				}];
+				return [{
+					type: "text",
+					text: `${String(result.entries?.length ?? 0)} coverage entry(ies)`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			let outcomeFilter;
+			if (args.outcome !== void 0 && args.outcome !== "") {
+				outcomeFilter = args.outcome.trim().toLowerCase().replaceAll("-", "_").replaceAll(" ", "_");
+				if (outcomeFilter !== void 0 && !VALID_OUTCOMES.includes(outcomeFilter)) return {
+					success: false,
+					error: `Invalid outcome: '${args.outcome}'. Must be one of: [${VALID_OUTCOMES.join(", ")}]`,
+					entries: [],
+					filtered_count: 0,
+					total_count: coverage.size,
+					outcome_counts: {}
+				};
+			}
+			const surfaceFilter = args.surface?.toLowerCase() ?? "";
+			const entries = coverageEntries().filter((entry) => outcomeFilter === void 0 || entry["outcome"] === outcomeFilter).filter((entry) => surfaceFilter === "" || String(entry["surface"]).toLowerCase().includes(surfaceFilter)).sort((a, b) => String(a["created_at"]).localeCompare(String(b["created_at"]))).map((entry) => {
+				const listing = {
+					entry_id: entry.entry_id,
+					surface: entry["surface"],
+					risk_area: entry["risk_area"],
+					outcome: entry["outcome"],
+					created_at: entry["created_at"]
+				};
+				const evidence = entry["evidence"];
+				if (typeof evidence === "string" && evidence !== "") listing["evidence"] = evidence.length > 240 ? `${evidence.slice(0, 240)}...` : evidence;
+				const history = entry["history"];
+				if (history !== void 0 && history.length > 0) listing["previous_outcomes"] = history.map((item) => item["outcome"]);
+				return listing;
+			});
+			return {
+				success: true,
+				entries,
+				filtered_count: entries.length,
+				total_count: coverage.size,
+				outcome_counts: outcomeCounts()
+			};
+		})
+	}));
+	const noteList = () => notes.values().map((entry) => ({
+		...entry,
+		id: String(entry["id"] ?? "")
+	}));
+	ctx.tools.register(defineTool({
+		name: "create_note",
+		description: "Create a persistent note shared across the scan team (categories: general/findings/methodology/questions/plan/wiki).",
+		parameters: {
+			title: {
+				type: "string",
+				required: true,
+				description: "Short note title."
+			},
+			content: {
+				type: "string",
+				required: true,
+				description: "The note body."
+			},
+			category: {
+				type: "string",
+				enum: [...VALID_NOTE_CATEGORIES],
+				description: "Note category (default general)."
+			},
+			tags: {
+				type: "array",
+				items: { type: "string" },
+				description: "Optional tags."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					note_id: { type: "string" },
+					message: { type: "string" },
+					total_count: { type: "integer" },
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				return [{
+					type: "text",
+					text: result.success ? "note created" : `create_note failed: ${result.error ?? "unknown"}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			const title = (args.title ?? "").trim();
+			const content = (args.content ?? "").trim();
+			const category = (args.category ?? "general").trim();
+			if (title === "") return {
+				success: false,
+				error: "Title cannot be empty"
+			};
+			if (content === "") return {
+				success: false,
+				error: "Content cannot be empty"
+			};
+			if (!VALID_NOTE_CATEGORIES.includes(category)) return {
+				success: false,
+				error: `Invalid category. Must be one of: ${VALID_NOTE_CATEGORIES.join(", ")}`
+			};
+			const id = generateId(new Set(noteList().map((note) => note.id)));
+			if (id === null) return {
+				success: false,
+				error: "could not allocate a note id"
+			};
+			const now = isoNow();
+			notes.set(id, {
+				id,
+				title,
+				content,
+				category,
+				tags: args.tags ?? [],
+				created_at: now,
+				updated_at: now
+			});
+			await notes.persist();
+			return {
+				success: true,
+				note_id: id,
+				message: `Note '${title}' created successfully`,
+				total_count: notes.size
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "list_notes",
+		description: "List notes (filters compose; newest first).",
+		parameters: {
+			category: {
+				type: "string",
+				description: "Exact category filter."
+			},
+			tags: {
+				type: "array",
+				items: { type: "string" },
+				description: "ANY-match tag filter."
+			},
+			search: {
+				type: "string",
+				description: "Substring match on title or content."
+			},
+			include_content: {
+				type: "boolean",
+				description: "Full content instead of a 280-char preview."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					notes: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {},
+							additionalProperties: true
+						},
+						required: true
+					},
+					filtered_count: {
+						type: "integer",
+						required: true
+					},
+					total_count: {
+						type: "integer",
+						required: true
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				return [{
+					type: "text",
+					text: `${String(value.notes?.length ?? 0)} note(s)`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			const category = args.category?.trim() ?? "";
+			const search = args.search?.toLowerCase() ?? "";
+			const tags = args.tags ?? [];
+			const entries = noteList().filter((note) => category === "" || note["category"] === category).filter((note) => tags.length === 0 || tags.some((tag) => note["tags"]?.includes(tag) === true)).filter((note) => search === "" || String(note["title"]).toLowerCase().includes(search) || String(note["content"]).toLowerCase().includes(search)).sort((a, b) => String(b["created_at"]).localeCompare(String(a["created_at"]))).map((note) => {
+				const listing = {
+					note_id: note.id,
+					title: note["title"],
+					category: note["category"],
+					tags: note["tags"],
+					created_at: note["created_at"],
+					updated_at: note["updated_at"]
+				};
+				const content = String(note["content"] ?? "");
+				listing[args.include_content === true ? "content" : "content_preview"] = args.include_content === true ? content : content.length > 280 ? `${content.slice(0, 280)}...` : content;
+				return listing;
+			});
+			return {
+				success: true,
+				notes: entries,
+				filtered_count: entries.length,
+				total_count: notes.size
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "get_note",
+		description: "Fetch one note by id.",
+		parameters: { note_id: {
+			type: "string",
+			required: true,
+			description: "Note id from list_notes or create_note."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					note: {
+						type: "object",
+						properties: {},
+						additionalProperties: true
+					},
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				return [{
+					type: "text",
+					text: result.success ? "note returned" : `get_note failed: ${result.error ?? "unknown"}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const noteId = (rawArgs.note_id ?? "").trim();
+			if (noteId === "") return {
+				success: false,
+				error: "Note ID cannot be empty"
+			};
+			const note = notes.get(noteId);
+			if (note === void 0) return {
+				success: false,
+				error: `Note with ID '${noteId}' not found`
+			};
+			return {
+				success: true,
+				note: {
+					...note,
+					note_id: noteId
+				}
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "update_note",
+		description: "Revise a note (only the fields you pass change; updated_at always bumps).",
+		parameters: {
+			note_id: {
+				type: "string",
+				required: true,
+				description: "Note id."
+			},
+			title: {
+				type: "string",
+				description: "Replacement title."
+			},
+			content: {
+				type: "string",
+				description: "Replacement content."
+			},
+			tags: {
+				type: "array",
+				items: { type: "string" },
+				description: "Replacement tags (full replace)."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					note_id: { type: "string" },
+					message: { type: "string" },
+					total_count: { type: "integer" },
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				return [{
+					type: "text",
+					text: result.success ? "note updated" : `update_note failed: ${result.error ?? "unknown"}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			const noteId = (args.note_id ?? "").trim();
+			const note = notes.get(noteId);
+			if (note === void 0) return {
+				success: false,
+				error: `Note with ID '${noteId}' not found`
+			};
+			if (args.title !== void 0 && args.title.trim() === "") return {
+				success: false,
+				error: "Title cannot be empty"
+			};
+			if (args.content !== void 0 && args.content.trim() === "") return {
+				success: false,
+				error: "Content cannot be empty"
+			};
+			if (args.title !== void 0) note["title"] = args.title.trim();
+			if (args.content !== void 0) note["content"] = args.content.trim();
+			if (args.tags !== void 0) note["tags"] = args.tags;
+			note["updated_at"] = isoNow();
+			await notes.persist();
+			return {
+				success: true,
+				note_id: noteId,
+				message: `Note '${String(note["title"])}' updated successfully`,
+				total_count: notes.size
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "delete_note",
+		description: "Delete a note by id.",
+		parameters: { note_id: {
+			type: "string",
+			required: true,
+			description: "Note id."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					note_id: { type: "string" },
+					message: { type: "string" },
+					total_count: { type: "integer" },
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				return [{
+					type: "text",
+					text: result.success ? "note deleted" : `delete_note failed: ${result.error ?? "unknown"}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const noteId = (rawArgs.note_id ?? "").trim();
+			const note = notes.get(noteId);
+			if (note === void 0) return {
+				success: false,
+				error: `Note with ID '${noteId}' not found`
+			};
+			notes.delete(noteId);
+			await notes.persist();
+			return {
+				success: true,
+				note_id: noteId,
+				message: `Note '${String(note["title"])}' deleted successfully`,
+				total_count: notes.size
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "think",
+		description: "Record a private reasoning step (no storage; use notes for persistent knowledge).",
+		parameters: { thought: {
+			type: "string",
+			required: true,
+			description: "The reasoning step."
+		} },
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					message: { type: "string" },
+					error: { type: "string" }
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				return [{
+					type: "text",
+					text: result.success ? "recorded" : `think failed: ${result.error ?? "unknown"}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			if ((rawArgs.thought ?? "").trim() === "") return {
+				success: false,
+				error: "Thought cannot be empty"
+			};
+			return {
+				success: true,
+				message: "Thought recorded"
+			};
+		})
+	}));
+	ctx.tools.register(defineTool({
+		name: "finish_scan",
+		description: "Complete the scan: validates the four report sections, records the coverage summary, writes the final artifacts, and marks the scan completed. Root agent only.",
+		parameters: {
+			executive_summary: {
+				type: "string",
+				required: true,
+				description: "Non-technical summary for stakeholders."
+			},
+			methodology: {
+				type: "string",
+				required: true,
+				description: "How the scan was conducted."
+			},
+			technical_analysis: {
+				type: "string",
+				required: true,
+				description: "Technical findings analysis."
+			},
+			recommendations: {
+				type: "string",
+				required: true,
+				description: "Prioritized remediation recommendations."
+			}
+		},
+		output: {
+			schema: {
+				type: "object",
+				properties: {
+					success: {
+						type: "boolean",
+						required: true
+					},
+					scan_completed: { type: "boolean" },
+					message: { type: "string" },
+					vulnerabilities_found: { type: "integer" },
+					coverage_recorded: { type: "integer" },
+					coverage_outcomes: {
+						type: "object",
+						properties: {},
+						additionalProperties: true
+					},
+					coverage_warning: { type: "string" },
+					unresolved_surfaces: {
+						type: "array",
+						items: {
+							type: "object",
+							properties: {},
+							additionalProperties: true
+						}
+					},
+					warning: { type: "string" },
+					error: { type: "string" },
+					errors: {
+						type: "array",
+						items: { type: "string" }
+					}
+				},
+				additionalProperties: false
+			},
+			render: (_args, value) => {
+				const result = value;
+				const reason = result.error ?? result.errors?.join("; ") ?? "unknown";
+				return [{
+					type: "text",
+					text: result.success ? "scan completed" : `finish_scan failed: ${reason}`
+				}];
+			}
+		},
+		execute: (async (rawArgs) => {
+			const args = rawArgs;
+			if (config.allowFinish === false) return {
+				success: false,
+				scan_completed: false,
+				error: "This tool can only be used by the root/main agent. If you are a subagent, use agent_finish instead"
+			};
+			const sections = {
+				executiveSummary: (args.executive_summary ?? "").trim(),
+				methodology: (args.methodology ?? "").trim(),
+				technicalAnalysis: (args.technical_analysis ?? "").trim(),
+				recommendations: (args.recommendations ?? "").trim()
+			};
+			const errors = [];
+			if (sections.executiveSummary === "") errors.push("Executive summary cannot be empty");
+			if (sections.methodology === "") errors.push("Methodology cannot be empty");
+			if (sections.technicalAnalysis === "") errors.push("Technical analysis cannot be empty");
+			if (sections.recommendations === "") errors.push("Recommendations cannot be empty");
+			if (errors.length > 0) return {
+				success: false,
+				error: "Validation failed",
+				errors
+			};
+			const summary = {
+				coverage_recorded: coverage.size,
+				coverage_outcomes: outcomeCounts()
+			};
+			if (coverage.size === 0) summary["coverage_warning"] = "No coverage was recorded for this scan. The report cannot state what was and was not tested; record coverage with record_coverage in future scans.";
+			else {
+				const unresolved = coverageEntries().filter((entry) => entry["outcome"] === "needs_follow_up").map((entry) => ({
+					surface: entry["surface"],
+					risk_area: entry["risk_area"]
+				}));
+				if (unresolved.length > 0) {
+					summary["coverage_warning"] = `${String(unresolved.length)} surface(s) still need follow-up; they are listed in unresolved_surfaces.`;
+					summary["unresolved_surfaces"] = unresolved;
+				}
+			}
+			const reporting = ctx.pentestReporting;
+			if (reporting === void 0) return {
+				success: true,
+				scan_completed: true,
+				message: "Scan completed (not persisted)",
+				warning: "Results could not be persisted - report state unavailable",
+				...summary
+			};
+			await reporting.finishScan(sections);
+			return {
+				success: true,
+				scan_completed: true,
+				message: "Scan completed successfully",
+				vulnerabilities_found: reporting.state.vulnerabilityReports.length,
+				...summary
+			};
+		})
+	}));
+	return handle;
+}
+//#endregion
+export { VALID_NOTE_CATEGORIES, VALID_OUTCOMES, apply, inject, name, normalizeTargetIdentity };
+
+//# sourceMappingURL=index.js.map