@ycodium-ai/plugin-pentest 0.0.0-stage → 0.2.2944

package/dist/index.js

@@ -0,0 +1,1164 @@
+// src/index.ts
+import { definePlugin } from "@ycodium-ai/plugin-api";
+
+// locales/en.json
+var en_default = {
+  board: {
+    title: "Assessment record",
+    goal: "Goal",
+    target: "Target",
+    objective: "Objective",
+    authorization: "Authorization note",
+    authorizationHint: "An audit note. It does not grant permission.",
+    counts: "{{intents}} intents \xB7 {{facts}} evidence \xB7 {{findings}} findings \xB7 {{assets}} assets",
+    window: "The panel shows {{shown}} of {{total}} records. The report is the full store.",
+    loading: "Loading the record",
+    empty: "No record on this session yet",
+    open: "Open session",
+    related: "Delegated sessions",
+    relatedEmpty: "No delegated session has written to this record",
+    tabs: {
+      explore: "Explore",
+      findings: "Findings",
+      assets: "Assets",
+      report: "Report"
+    }
+  },
+  explore: {
+    empty: "Select a record to see its detail",
+    edge: {
+      spawns: "spawns",
+      yields: "yields",
+      derived_from: "derived from",
+      proves: "proves",
+      parent: "parent"
+    }
+  },
+  node: {
+    goal: "Goal",
+    intent: "Intent",
+    fact: "Evidence",
+    finding: "Finding",
+    asset: "Asset",
+    confidence: "Confidence {{value}}",
+    steps: "Observations",
+    close: "Close detail"
+  },
+  findings: {
+    empty: "No findings recorded",
+    all: "All severities",
+    affected: "Affected asset",
+    filter: "Severity"
+  },
+  severity: {
+    critical: "Critical",
+    high: "High",
+    medium: "Medium",
+    low: "Low",
+    info: "Info"
+  },
+  assets: {
+    empty: "No assets recorded",
+    list: "List",
+    tree: "Tree",
+    root: "Root",
+    filter: "Filter assets",
+    meta: "Notes"
+  },
+  assetType: {
+    "root-domain": "Root domain",
+    subdomain: "Subdomain",
+    ip: "IP",
+    service: "Service",
+    app: "App",
+    endpoint: "Endpoint"
+  },
+  factKind: {
+    port: "Port",
+    service: "Service",
+    vuln: "Issue",
+    finding: "Finding",
+    http: "HTTP",
+    info: "Info"
+  },
+  report: {
+    copy: "Copy Markdown",
+    download: "Download Markdown",
+    copied: "Report copied",
+    copyFailed: "Could not copy the report",
+    empty: "The report appears after a goal is recorded",
+    loading: "Preparing the report"
+  },
+  preset: {
+    description: "Record a goal, intents, evidence, assets, and findings on this session. The protocol is added to later turns."
+  },
+  hero: {
+    title: "Assessment record",
+    body: "Choose this preset before the first turn. The protocol is added to every later turn, and the session panel appears after the first goal.",
+    goal: "Goal",
+    evidence: "Evidence",
+    assets: "Assets",
+    findings: "Findings",
+    current: "This session records {{target}}"
+  },
+  settings: {
+    title: "Assessment record",
+    lead: "The panel shows a window of the latest records. Exports read the full store. A delegated session can only submit onto its parent.",
+    window: "Records kept in the session panel",
+    windowHint: "From 20 to 200. The stored record is not trimmed.",
+    authorization: "Include the authorization note in exported reports",
+    saved: "Saved",
+    card: {
+      title: "Assessment record",
+      description: "Window size and report options are in the Assessment record section."
+    }
+  },
+  card: {
+    recorded: "Recorded {{id}}",
+    summary: "Recorded",
+    report: "Report ready"
+  },
+  tool: {
+    add_goal: "Add goal",
+    add_intent: "Add intent",
+    add_fact: "Add evidence",
+    add_finding: "Add finding",
+    add_asset: "Add asset",
+    state: "Record state",
+    graph: "Record graph",
+    report: "Assessment report",
+    submit: "Submit record"
+  }
+};
+
+// src/names.ts
+var PLUGIN_ID = "pentest";
+var GRAPH_PROJECTION = "graph";
+var MOUNTED_PROJECTION = "mounted";
+var PRESET_ID = "pentest";
+var TOOL_SHORT_NAMES = [
+  "add_goal",
+  "add_intent",
+  "add_fact",
+  "add_finding",
+  "add_asset",
+  "state",
+  "graph",
+  "report",
+  "submit"
+];
+var SUBMIT_TOOL = "submit";
+var wireName = (name) => `${PLUGIN_ID}_${name}`;
+var DECISION_WIRE_NAMES = new Set(
+  TOOL_SHORT_NAMES.filter((name) => name !== SUBMIT_TOOL).map((name) => wireName(name))
+);
+var SUBMIT_WIRE_NAME = wireName(SUBMIT_TOOL);
+
+// src/guard.ts
+async function decideRecordGuard(name, threadId, parentOf2) {
+  if (!DECISION_WIRE_NAMES.has(name) && name !== SUBMIT_WIRE_NAME) return { decision: "allow" };
+  let parent = null;
+  if (threadId !== null && threadId.length > 0) {
+    try {
+      parent = await parentOf2(threadId);
+    } catch {
+      return {
+        decision: "deny",
+        reason: "This session could not be read, so the record tools are refused."
+      };
+    }
+  }
+  const delegated = parent !== null && parent.length > 0;
+  if (delegated && name !== SUBMIT_WIRE_NAME) {
+    return {
+      decision: "deny",
+      reason: "A delegated session can only record through pentest_submit."
+    };
+  }
+  if (!delegated && name === SUBMIT_WIRE_NAME) {
+    return { decision: "deny", reason: "pentest_submit only runs in a delegated session." };
+  }
+  return { decision: "allow" };
+}
+
+// src/limits.ts
+var WINDOW_DEFAULT = 200;
+var WINDOW_MIN = 20;
+var WINDOW_MAX = 200;
+var TEXT_CAP = 4e3;
+var STEP_CAP = 1e3;
+var STEP_MAX = 20;
+var REPORT_TEXT_CAP = 24e3;
+
+// src/model.ts
+var FACT_KINDS = ["port", "service", "vuln", "finding", "http", "info"];
+var SEVERITIES = ["critical", "high", "medium", "low", "info"];
+var ASSET_TYPES = ["root-domain", "subdomain", "ip", "service", "app", "endpoint"];
+var emptyCounters = () => ({ intent: 0, fact: 0, finding: 0, asset: 0, edge: 0 });
+var emptyEngagement = () => ({
+  goal: null,
+  nodes: [],
+  assets: [],
+  edges: [],
+  counters: emptyCounters()
+});
+var countsOf = (engagement) => ({
+  intents: engagement.nodes.filter((node) => node.kind === "intent").length,
+  facts: engagement.nodes.filter((node) => node.kind === "fact").length,
+  findings: engagement.nodes.filter((node) => node.kind === "finding").length,
+  assets: engagement.assets.length
+});
+var fail = (error) => ({ ok: false, error });
+var text = (value, cap) => {
+  if (typeof value !== "string") return null;
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.length > cap) return null;
+  return trimmed;
+};
+var optionalText = (value, cap) => {
+  if (value === void 0 || value === null || value === "") return "";
+  return text(value, cap);
+};
+var oneOf = (value, allowed) => typeof value === "string" && allowed.includes(value) ? value : null;
+var bump = (counters, key) => {
+  const n = counters[key] + 1;
+  return { counters: { ...counters, [key]: n }, n };
+};
+function addGoal(_current, input) {
+  const target = text(input.target, 500);
+  const objective = text(input.objective, TEXT_CAP);
+  const authorization = optionalText(input.authorization, TEXT_CAP);
+  if (target === null) return fail("target is required");
+  if (objective === null) return fail("objective is required");
+  if (authorization === null) return fail("authorization is too long");
+  return {
+    ok: true,
+    id: "goal-1",
+    engagement: {
+      goal: { id: "goal-1", target, objective, authorization },
+      nodes: [],
+      assets: [],
+      edges: [],
+      counters: emptyCounters()
+    }
+  };
+}
+function addIntent(current, input) {
+  if (current.goal === null) return fail("record a goal first");
+  const anchorKind = oneOf(input.anchorKind, ["goal", "fact"]);
+  const anchorId = text(input.anchorId, 80);
+  const title = text(input.title, 200);
+  const detail = optionalText(input.detail, TEXT_CAP);
+  if (anchorKind === null || anchorId === null) return fail("intent needs exactly one anchor");
+  if (title === null) return fail("title is required");
+  if (detail === null) return fail("detail is too long");
+  if (anchorKind === "goal" && anchorId !== current.goal.id)
+    return fail("goal anchor was not found");
+  if (anchorKind === "fact" && !current.nodes.some((node2) => node2.kind === "fact" && node2.id === anchorId)) {
+    return fail("fact anchor was not found");
+  }
+  const intent = bump(current.counters, "intent");
+  const edge = bump(intent.counters, "edge");
+  const id = `intent-${String(intent.n)}`;
+  const node = { id, kind: "intent", title, detail };
+  const link = {
+    id: `edge-${String(edge.n)}`,
+    kind: anchorKind === "goal" ? "spawns" : "derived_from",
+    sourceId: anchorId,
+    targetId: id
+  };
+  return {
+    ok: true,
+    id,
+    engagement: {
+      ...current,
+      counters: edge.counters,
+      nodes: [...current.nodes, node],
+      edges: [...current.edges, link]
+    }
+  };
+}
+function addFact(current, input) {
+  const intentId = text(input.intentId, 80);
+  const factKind = oneOf(input.factKind, FACT_KINDS);
+  const detail = text(input.detail, TEXT_CAP);
+  const target = optionalText(input.target, 500);
+  if (intentId === null || !current.nodes.some((node2) => node2.kind === "intent" && node2.id === intentId)) {
+    return fail("intent was not found");
+  }
+  if (factKind === null) return fail("fact kind is not recognized");
+  if (detail === null) return fail("detail is required");
+  if (target === null) return fail("target is too long");
+  const confidence = readConfidence(input.confidence);
+  if (confidence === null) return fail("confidence must be from 0 to 1");
+  const fact = bump(current.counters, "fact");
+  const edge = bump(fact.counters, "edge");
+  const id = `fact-${String(fact.n)}`;
+  const node = { id, kind: "fact", factKind, intentId, target, detail, confidence };
+  const link = {
+    id: `edge-${String(edge.n)}`,
+    kind: "yields",
+    sourceId: intentId,
+    targetId: id
+  };
+  return {
+    ok: true,
+    id,
+    engagement: {
+      ...current,
+      counters: edge.counters,
+      nodes: [...current.nodes, node],
+      edges: [...current.edges, link]
+    }
+  };
+}
+function addFinding(current, input) {
+  const intentId = text(input.intentId, 80);
+  const title = text(input.title, 200);
+  const severity = oneOf(input.severity, SEVERITIES);
+  const description = optionalText(input.description, TEXT_CAP);
+  if (intentId === null || !current.nodes.some((node2) => node2.kind === "intent" && node2.id === intentId)) {
+    return fail("intent was not found");
+  }
+  if (title === null) return fail("title is required");
+  if (severity === null) return fail("severity is not recognized");
+  if (description === null) return fail("description is too long");
+  const steps = readSteps(input.steps);
+  if (steps === null) return fail("at least one observation step is required");
+  const affected = optionalAsset(current, input.affectedAssetId);
+  if (affected === null) return fail("affected asset was not found");
+  const finding = bump(current.counters, "finding");
+  const edge = bump(finding.counters, "edge");
+  const id = `finding-${String(finding.n)}`;
+  const node = {
+    id,
+    kind: "finding",
+    intentId,
+    title,
+    severity,
+    description,
+    steps,
+    ...affected.length > 0 ? { affectedAssetId: affected } : {}
+  };
+  const link = {
+    id: `edge-${String(edge.n)}`,
+    kind: "proves",
+    sourceId: intentId,
+    targetId: id
+  };
+  return {
+    ok: true,
+    id,
+    engagement: {
+      ...current,
+      counters: edge.counters,
+      nodes: [...current.nodes, node],
+      edges: [...current.edges, link]
+    }
+  };
+}
+function addAsset(current, input) {
+  if (current.goal === null) return fail("record a goal first");
+  const type = oneOf(input.type, ASSET_TYPES);
+  const value = text(input.value, 500);
+  const meta = optionalText(input.meta, TEXT_CAP);
+  if (type === null) return fail("asset type is not recognized");
+  if (value === null) return fail("value is required");
+  if (meta === null) return fail("meta is too long");
+  const parent = optionalAsset(current, input.parentId);
+  if (parent === null) return fail("parent asset was not found");
+  const asset = bump(current.counters, "asset");
+  const id = `asset-${String(asset.n)}`;
+  let counters = asset.counters;
+  let edges = current.edges;
+  if (parent.length > 0) {
+    const edge = bump(counters, "edge");
+    counters = edge.counters;
+    edges = [
+      ...edges,
+      { id: `edge-${String(edge.n)}`, kind: "parent", sourceId: parent, targetId: id }
+    ];
+  }
+  const node = { id, type, value, meta };
+  return {
+    ok: true,
+    id,
+    engagement: { ...current, counters, assets: [...current.assets, node], edges }
+  };
+}
+function applySubmit(current, input) {
+  if (input.recordKind === "fact") {
+    return addFact(current, input);
+  }
+  if (input.recordKind === "asset") return addAsset(current, input);
+  return addFinding(current, input);
+}
+function windowOf(engagement, limit) {
+  const cap = clampWindow(limit);
+  const nodes = engagement.nodes.slice(-cap);
+  const assets = engagement.assets.slice(-cap);
+  const keep = /* @__PURE__ */ new Set([
+    ...engagement.goal === null ? [] : [engagement.goal.id],
+    ...nodes.map((node) => node.id),
+    ...assets.map((asset) => asset.id)
+  ]);
+  const edges = engagement.edges.filter((edge) => keep.has(edge.sourceId) && keep.has(edge.targetId)).slice(-cap);
+  const totals = countsOf(engagement);
+  const shown = countsOf({ ...engagement, nodes, assets });
+  return {
+    goal: engagement.goal,
+    nodes,
+    assets,
+    edges,
+    counts: shown,
+    totals,
+    truncated: nodes.length !== engagement.nodes.length || assets.length !== engagement.assets.length || edges.length !== engagement.edges.filter((edge) => keep.has(edge.sourceId) && keep.has(edge.targetId)).length
+  };
+}
+function reportMarkdown(engagement, includeAuthorization) {
+  if (engagement.goal === null) return "No goal has been recorded.\n";
+  const lines = [
+    "# Assessment record",
+    "",
+    "## Goal",
+    "",
+    `- Target: ${engagement.goal.target}`,
+    `- Objective: ${engagement.goal.objective}`
+  ];
+  if (includeAuthorization) {
+    lines.push(`- Authorization note: ${engagement.goal.authorization || "(none)"}`);
+    lines.push("- The authorization note is an audit field. It does not grant permission.");
+  }
+  const findings = engagement.nodes.filter((node) => node.kind === "finding");
+  const findingBody = [];
+  for (const finding of findings) {
+    if (findingBody.length > 0) findingBody.push("");
+    const asset = finding.affectedAssetId === void 0 ? "" : ` (${finding.affectedAssetId})`;
+    findingBody.push(
+      `### ${finding.severity}: ${finding.title}`,
+      "",
+      `Intent: ${finding.intentId}${asset}`,
+      ""
+    );
+    if (finding.description.length > 0) findingBody.push(finding.description, "");
+    findingBody.push("Observations:");
+    finding.steps.forEach((step, index) => findingBody.push(`${String(index + 1)}. ${step}`));
+  }
+  appendReportSection(lines, "Findings", findingBody);
+  const assetBody = engagement.assets.map((asset) => {
+    const parent = engagement.edges.find(
+      (edge) => edge.kind === "parent" && edge.targetId === asset.id
+    );
+    return `- ${asset.id} ${asset.type} ${asset.value} (parent: ${parent?.sourceId ?? "none"})`;
+  });
+  appendReportSection(lines, "Assets", assetBody);
+  const facts = engagement.nodes.filter((node) => node.kind === "fact");
+  appendReportSection(
+    lines,
+    "Evidence",
+    facts.map(
+      (fact) => `- ${fact.id} ${fact.factKind} on ${fact.intentId} (${String(fact.confidence)}): ${fact.detail}`
+    )
+  );
+  const intents = engagement.nodes.filter((node) => node.kind === "intent");
+  appendReportSection(
+    lines,
+    "Intents",
+    intents.map((intent) => `- ${intent.id} ${intent.title}`)
+  );
+  lines.push("");
+  const markdown = lines.join("\n");
+  if (markdown.length <= REPORT_TEXT_CAP) return markdown;
+  return `${markdown.slice(0, REPORT_TEXT_CAP)}
+
+[truncated]
+`;
+}
+function appendReportSection(lines, title, body) {
+  lines.push("", `## ${title}`, "");
+  if (body.length === 0) {
+    lines.push("None recorded.");
+    return;
+  }
+  lines.push(...body);
+}
+function clampWindow(value) {
+  if (!Number.isFinite(value)) return WINDOW_MAX;
+  return Math.min(WINDOW_MAX, Math.max(WINDOW_MIN, Math.floor(value)));
+}
+function isEngagement(value) {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return record.goal !== void 0 && Array.isArray(record.nodes) && Array.isArray(record.assets) && Array.isArray(record.edges) && typeof record.counters === "object" && record.counters !== null;
+}
+function readConfidence(value) {
+  if (value === void 0 || value === null || value === "") return 0.5;
+  if (typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > 1) return null;
+  return value;
+}
+function readSteps(value) {
+  if (!Array.isArray(value) || value.length === 0 || value.length > STEP_MAX) return null;
+  const steps = [];
+  for (const step of value) {
+    const line = text(step, STEP_CAP);
+    if (line === null) return null;
+    steps.push(line);
+  }
+  return steps;
+}
+function optionalAsset(current, value) {
+  if (value === void 0 || value === null || value === "") return "";
+  const id = text(value, 80);
+  if (id === null) return null;
+  return current.assets.some((asset) => asset.id === id) ? id : null;
+}
+
+// src/protocol.ts
+var PROTOCOL_TEXT = [
+  "Assessment record protocol.",
+  "",
+  "Record an authorized assessment as a graph on this session. The authorization field is an audit note: who granted permission, or a written reference. It is not a permission check. Host approval still applies to every other tool.",
+  "",
+  `Start with ${wireName("add_goal")}. One goal per session. A later goal resets only this session.`,
+  `Add one intent at a time with ${wireName("add_intent")} and exactly one anchor: the goal, or a fact already recorded. Cite the id the tool returns.`,
+  `Record evidence with ${wireName("add_fact")} on that intent.`,
+  `Record a confirmed issue with ${wireName("add_finding")}. Include a severity and at least one observation of what was seen. Do not put exploit payloads, proof-of-concept code, or attack instructions in the record.`,
+  `Record assets with ${wireName("add_asset")}. Record a parent before its children. An empty parent id is a root asset.`,
+  `Read the complete store with ${wireName("state")}, ${wireName("graph")}, and ${wireName("report")}. The session panel is a window of at most 200 nodes, assets, and edges.`,
+  `A delegated child session may only call ${SUBMIT_WIRE_NAME}, aimed at an intent on its parent session. Decision and read tools are refused there. The parent session cannot call ${SUBMIT_WIRE_NAME}.`,
+  "",
+  "Edges are spawns (goal to intent), yields (intent to fact), derived_from (fact to intent), proves (intent to finding), and parent (asset to asset).",
+  "Respond in the user's language."
+].join("\n");
+function turnContext(input) {
+  if (input.target === null) return "Assessment record for this session: no goal yet.";
+  const target = input.target.length > 120 ? `${input.target.slice(0, 120)}\u2026` : input.target;
+  return `Assessment record: target ${target}. Intents ${String(input.intents)}, evidence ${String(input.facts)}, findings ${String(input.findings)}, assets ${String(input.assets)}.`;
+}
+
+// src/related.ts
+async function relatedSessions(projections, threadId) {
+  const current = await projections.getThread(threadId);
+  if (current === null) return [];
+  const page = await projections.listThreads({ limit: 100, includeArchived: false });
+  const found = [];
+  for (const shell of page.threads) {
+    if (found.length >= 20) break;
+    if (shell.projectId !== current.projectId || shell.threadId === threadId) continue;
+    const thread = await projections.getThread(shell.threadId);
+    if (thread?.origin?.parentThreadId === threadId) {
+      found.push({ threadId: shell.threadId, title: shell.title });
+    }
+  }
+  return found;
+}
+
+// src/store.ts
+import * as NodeFSP from "node:fs/promises";
+import * as NodePath from "node:path";
+var defaultPrefs = () => ({
+  windowLimit: WINDOW_DEFAULT,
+  includeAuthorization: true
+});
+function createStore(dataDir) {
+  const file = NodePath.join(dataDir, "record.json");
+  let chain = Promise.resolve();
+  const listeners = /* @__PURE__ */ new Set();
+  const exclusive = (run) => {
+    const next = chain.then(run, run);
+    chain = next.then(
+      () => void 0,
+      () => void 0
+    );
+    return next;
+  };
+  const load = async () => {
+    try {
+      const parsed = JSON.parse(await NodeFSP.readFile(file, "utf8"));
+      return normalizeFile(parsed);
+    } catch {
+      return { prefs: defaultPrefs(), sessions: {} };
+    }
+  };
+  const save = async (value) => {
+    await NodeFSP.mkdir(dataDir, { recursive: true });
+    const temp = `${file}.${String(process.pid)}.tmp`;
+    await NodeFSP.writeFile(temp, `${JSON.stringify(value)}
+`);
+    await NodeFSP.rename(temp, file);
+  };
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    read(threadId) {
+      return exclusive(async () => (await load()).sessions[threadId] ?? emptyEngagement());
+    },
+    prefs() {
+      return exclusive(async () => (await load()).prefs);
+    },
+    update(threadId, recipe) {
+      return exclusive(async () => {
+        const current = await load();
+        const engagement = recipe(current.sessions[threadId] ?? emptyEngagement());
+        await save({ ...current, sessions: { ...current.sessions, [threadId]: engagement } });
+        for (const listener of listeners) listener();
+        return engagement;
+      });
+    },
+    writePrefs(patch) {
+      return exclusive(async () => {
+        const current = await load();
+        const prefs = {
+          windowLimit: patch.windowLimit === void 0 ? current.prefs.windowLimit : clampWindow(patch.windowLimit),
+          includeAuthorization: patch.includeAuthorization === void 0 ? current.prefs.includeAuthorization : patch.includeAuthorization
+        };
+        await save({ ...current, prefs });
+        for (const listener of listeners) listener();
+        return prefs;
+      });
+    }
+  };
+}
+function normalizeFile(value) {
+  if (typeof value !== "object" || value === null) return { prefs: defaultPrefs(), sessions: {} };
+  const record = value;
+  const prefs = normalizePrefs(record.prefs);
+  const sessions = {};
+  if (typeof record.sessions === "object" && record.sessions !== null) {
+    for (const [threadId, engagement] of Object.entries(record.sessions)) {
+      if (isEngagement(engagement)) sessions[threadId] = engagement;
+    }
+  }
+  return { prefs, sessions };
+}
+function normalizePrefs(value) {
+  if (typeof value !== "object" || value === null) return defaultPrefs();
+  const record = value;
+  return {
+    windowLimit: typeof record.windowLimit === "number" ? clampWindow(record.windowLimit) : WINDOW_DEFAULT,
+    includeAuthorization: record.includeAuthorization !== false
+  };
+}
+
+// src/tools.ts
+import {
+  pluginJsonByteLength
+} from "@ycodium-ai/plugin-api";
+var saved = (name, id, engagement) => ({
+  text: `Recorded ${id}.`,
+  presentation: presentationOf(name, id, engagement)
+});
+var failure = (error) => ({ text: error, isError: true });
+function recordTools(service) {
+  return [
+    tool(
+      "add_goal",
+      "Start or reset this session's assessment graph. authorization is an audit note, not a permission check.",
+      {
+        target: { type: "string", description: "What this session is about." },
+        objective: { type: "string", description: "What the record should establish." },
+        authorization: {
+          type: "string",
+          description: "Who granted permission, or a written reference. Stored as an audit note."
+        }
+      },
+      ["target", "objective"],
+      (args, invocation) => mutate(
+        service,
+        invocation,
+        "add_goal",
+        null,
+        (current) => addGoal(current, {
+          target: args["target"],
+          objective: args["objective"],
+          authorization: args["authorization"]
+        })
+      )
+    ),
+    tool(
+      "add_intent",
+      "Add one intent. Exactly one anchor: anchorKind goal or fact, plus that record's id.",
+      {
+        anchorKind: { type: "string", enum: ["goal", "fact"] },
+        anchorId: { type: "string" },
+        title: { type: "string" },
+        detail: { type: "string" }
+      },
+      ["anchorKind", "anchorId", "title"],
+      (args, invocation) => mutate(
+        service,
+        invocation,
+        "add_intent",
+        null,
+        (current) => addIntent(current, {
+          anchorKind: args["anchorKind"],
+          anchorId: args["anchorId"],
+          title: args["title"],
+          detail: args["detail"]
+        })
+      )
+    ),
+    tool(
+      "add_fact",
+      "Record evidence yielded by an intent.",
+      {
+        intentId: { type: "string" },
+        factKind: { type: "string", enum: ["port", "service", "vuln", "finding", "http", "info"] },
+        target: { type: "string" },
+        detail: { type: "string" },
+        confidence: { type: "number", description: "From 0 to 1. Defaults to 0.5." }
+      },
+      ["intentId", "factKind", "detail"],
+      (args, invocation) => mutate(
+        service,
+        invocation,
+        "add_fact",
+        null,
+        (current) => addFact(current, {
+          intentId: args["intentId"],
+          factKind: args["factKind"],
+          target: args["target"],
+          detail: args["detail"],
+          confidence: args["confidence"]
+        })
+      )
+    ),
+    tool(
+      "add_finding",
+      "Record a confirmed issue proved by an intent. steps are observations of what was seen, at least one. This tool does not execute anything.",
+      {
+        intentId: { type: "string" },
+        title: { type: "string" },
+        severity: { type: "string", enum: ["critical", "high", "medium", "low", "info"] },
+        description: { type: "string" },
+        steps: {
+          type: "array",
+          items: { type: "string" },
+          description: "Observations. At least one."
+        },
+        affectedAssetId: { type: "string" }
+      },
+      ["intentId", "title", "severity", "steps"],
+      (args, invocation) => mutate(
+        service,
+        invocation,
+        "add_finding",
+        null,
+        (current) => addFinding(current, {
+          intentId: args["intentId"],
+          title: args["title"],
+          severity: args["severity"],
+          description: args["description"],
+          steps: args["steps"],
+          affectedAssetId: args["affectedAssetId"]
+        })
+      )
+    ),
+    tool(
+      "add_asset",
+      "Record an asset. parentId empty means a root. Record the parent first.",
+      {
+        type: {
+          type: "string",
+          enum: ["root-domain", "subdomain", "ip", "service", "app", "endpoint"]
+        },
+        value: { type: "string" },
+        meta: { type: "string" },
+        parentId: { type: "string" }
+      },
+      ["type", "value"],
+      (args, invocation) => mutate(
+        service,
+        invocation,
+        "add_asset",
+        null,
+        (current) => addAsset(current, {
+          type: args["type"],
+          value: args["value"],
+          meta: args["meta"],
+          parentId: args["parentId"]
+        })
+      )
+    ),
+    tool(
+      "state",
+      "Read counts and the goal for this session's full store, not the panel window.",
+      {},
+      [],
+      async (_args, invocation) => {
+        const threadId = invocation.threadId;
+        if (threadId === null) return failure("no session");
+        const engagement = await service.read(threadId);
+        const counts = countsOf(engagement);
+        return {
+          text: engagement.goal === null ? "No goal has been recorded." : `Goal ${engagement.goal.id} on ${engagement.goal.target}. Intents ${String(counts.intents)}, evidence ${String(counts.facts)}, findings ${String(counts.findings)}, assets ${String(counts.assets)}.`,
+          presentation: presentationOf("state", engagement.goal?.id ?? "", engagement)
+        };
+      }
+    ),
+    tool(
+      "graph",
+      "Read the full assessment graph for this session.",
+      {},
+      [],
+      async (_args, invocation) => {
+        const threadId = invocation.threadId;
+        if (threadId === null) return failure("no session");
+        const engagement = await service.read(threadId);
+        const body = JSON.stringify({
+          goal: engagement.goal,
+          nodes: engagement.nodes,
+          assets: engagement.assets,
+          edges: engagement.edges
+        });
+        const text2 = body.length <= REPORT_TEXT_CAP ? body : `${body.slice(0, REPORT_TEXT_CAP)}
+[truncated]`;
+        return {
+          text: text2,
+          presentation: presentationOf("graph", engagement.goal?.id ?? "", engagement)
+        };
+      }
+    ),
+    tool(
+      "report",
+      "Read a Markdown report of the full store. When the session workspace is writable, also save pentest/report.md.",
+      {},
+      [],
+      async (_args, invocation) => {
+        const threadId = invocation.threadId;
+        if (threadId === null) return failure("no session");
+        const engagement = await service.read(threadId);
+        const markdown = reportMarkdown(engagement, await service.includeAuthorization());
+        const path = await writeReport(invocation.workspace, markdown);
+        const suffix = path === null ? "" : ` Saved ${path}.`;
+        return {
+          text: `${markdown}${suffix}`,
+          presentation: presentationOf("report", path ?? engagement.goal?.id ?? "", engagement)
+        };
+      }
+    ),
+    tool(
+      SUBMIT_TOOL,
+      "Delegated sessions only. Write one fact, asset, or finding onto an intent of the parent session.",
+      {
+        intentId: { type: "string" },
+        recordKind: { type: "string", enum: ["fact", "asset", "finding"] },
+        factKind: { type: "string", enum: ["port", "service", "vuln", "finding", "http", "info"] },
+        target: { type: "string" },
+        detail: { type: "string" },
+        confidence: { type: "number" },
+        type: {
+          type: "string",
+          enum: ["root-domain", "subdomain", "ip", "service", "app", "endpoint"]
+        },
+        value: { type: "string" },
+        meta: { type: "string" },
+        parentId: { type: "string" },
+        title: { type: "string" },
+        severity: { type: "string", enum: ["critical", "high", "medium", "low", "info"] },
+        description: { type: "string" },
+        steps: { type: "array", items: { type: "string" } },
+        affectedAssetId: { type: "string" }
+      },
+      ["intentId", "recordKind"],
+      async (args, invocation) => {
+        const threadId = invocation.threadId;
+        if (threadId === null) return failure("no session");
+        const parent = await service.parentOf(threadId);
+        if (parent === null || parent.length === 0)
+          return failure("pentest_submit only runs in a delegated session.");
+        const record = submitFrom(args);
+        if (record === null) return failure("recordKind is not recognized");
+        return mutate(
+          service,
+          invocation,
+          SUBMIT_TOOL,
+          parent,
+          (current) => applySubmit(current, record)
+        );
+      }
+    )
+  ];
+}
+function tool(name, description, properties, required, handle) {
+  return {
+    name,
+    description,
+    ...name === SUBMIT_TOOL ? {} : { whenPresetId: PRESET_ID },
+    inputSchema: {
+      type: "object",
+      properties,
+      ...required.length > 0 ? { required: [...required] } : {}
+    },
+    handle
+  };
+}
+async function mutate(service, invocation, name, threadId, recipe) {
+  const id = threadId ?? invocation.threadId;
+  if (id === null) return failure("no session");
+  const recorded = { current: null };
+  const engagement = await service.update(id, (current) => {
+    const next = recipe(current);
+    recorded.current = next;
+    return next.ok ? next.engagement : current;
+  });
+  const outcome = recorded.current;
+  if (outcome === null || !outcome.ok)
+    return failure(outcome === null ? "not recorded" : outcome.error);
+  await service.publish(id);
+  return saved(name, outcome.id, engagement);
+}
+function presentationOf(toolName, id, engagement) {
+  const counts = countsOf(engagement);
+  const body = {
+    kind: "pentest",
+    tool: toolName,
+    id,
+    counts: {
+      intents: counts.intents,
+      facts: counts.facts,
+      findings: counts.findings,
+      assets: counts.assets
+    },
+    target: engagement.goal?.target ?? ""
+  };
+  if (pluginJsonByteLength(body) > 1024 * 1024) return null;
+  return body;
+}
+async function writeReport(workspace, markdown) {
+  if (workspace?.mkdir === void 0 || workspace.writeFile === void 0) return null;
+  try {
+    await workspace.mkdir("pentest");
+    await workspace.writeFile("pentest/report.md", new TextEncoder().encode(markdown));
+    return "pentest/report.md";
+  } catch {
+    return null;
+  }
+}
+function submitFrom(args) {
+  const intentId = typeof args["intentId"] === "string" ? args["intentId"] : "";
+  const kind = args["recordKind"];
+  if (kind === "fact") {
+    return {
+      recordKind: "fact",
+      intentId,
+      factKind: args["factKind"],
+      target: args["target"],
+      detail: args["detail"],
+      confidence: args["confidence"]
+    };
+  }
+  if (kind === "asset") {
+    return {
+      recordKind: "asset",
+      intentId,
+      type: args["type"],
+      value: args["value"],
+      meta: args["meta"],
+      parentId: args["parentId"]
+    };
+  }
+  if (kind === "finding") {
+    return {
+      recordKind: "finding",
+      intentId,
+      title: args["title"],
+      severity: args["severity"],
+      description: args["description"],
+      steps: args["steps"],
+      affectedAssetId: args["affectedAssetId"]
+    };
+  }
+  return null;
+}
+
+// src/index.ts
+var pentestPlugin = definePlugin({
+  id: "pentest",
+  apiVersion: 4,
+  activate(ctx) {
+    const store = createStore(ctx.paths.dataDir);
+    ctx.sessionProjections.register({ name: GRAPH_PROJECTION });
+    ctx.sessionProjections.register({ name: MOUNTED_PROJECTION });
+    ctx.systemPrompt.context(async (turn) => {
+      if (turn.presetId !== PRESET_ID) return null;
+      try {
+        const engagement = await store.read(turn.threadId);
+        if (engagement.goal === null) return null;
+        const counts = countsOf(engagement);
+        return turnContext({
+          target: engagement.goal.target,
+          intents: counts.intents,
+          facts: counts.facts,
+          findings: counts.findings,
+          assets: counts.assets
+        });
+      } catch (error) {
+        ctx.log.warn("pentest turn context skipped", {
+          detail: error instanceof Error ? error.message : "unknown"
+        });
+        return null;
+      }
+    });
+    ctx.tools.guard(
+      (input) => decideRecordGuard(input.name, input.threadId, (threadId) => parentOf(ctx, threadId))
+    );
+    ctx.agentPresets.register({
+      id: PRESET_ID,
+      displayName: "Assessment record",
+      description: en_default.preset.description,
+      promptPrefix: PROTOCOL_TEXT
+    });
+    const service = createService(ctx, store);
+    ctx.toolkit({ name: "record", tools: recordTools(service) });
+    ctx.command({
+      name: "board",
+      description: "Read one session's assessment record.",
+      scope: "read",
+      payloadSchema: {
+        type: "object",
+        properties: { threadId: { type: "string" } },
+        required: ["threadId"]
+      },
+      handle: (payload) => snapshot(ctx, store, readString(payload["threadId"]))
+    });
+    ctx.command({
+      name: "report",
+      description: "Read the full Markdown report for one session.",
+      scope: "read",
+      payloadSchema: {
+        type: "object",
+        properties: { threadId: { type: "string" } },
+        required: ["threadId"]
+      },
+      handle: async (payload) => {
+        const threadId = readString(payload["threadId"]);
+        const engagement = await store.read(threadId);
+        const prefs = await store.prefs();
+        return { markdown: reportMarkdown(engagement, prefs.includeAuthorization) };
+      }
+    });
+    ctx.command({
+      name: "preferences",
+      description: "Update the panel window and whether reports include the authorization note.",
+      scope: "operate",
+      payloadSchema: {
+        type: "object",
+        properties: {
+          threadId: { type: "string" },
+          windowLimit: { type: "number" },
+          includeAuthorization: { type: "boolean" }
+        }
+      },
+      handle: async (payload) => {
+        const prefs = await store.writePrefs({
+          ...typeof payload["windowLimit"] === "number" ? { windowLimit: payload["windowLimit"] } : {},
+          ...typeof payload["includeAuthorization"] === "boolean" ? { includeAuthorization: payload["includeAuthorization"] } : {}
+        });
+        const threadId = readString(payload["threadId"]);
+        if (threadId.length > 0) await service.publish(threadId);
+        return { prefs };
+      }
+    });
+    ctx.stream({
+      name: "live",
+      description: "Follow one session's assessment record.",
+      scope: "read",
+      buffer: { latest: 1 },
+      payloadSchema: {
+        type: "object",
+        properties: { threadId: { type: "string" } },
+        required: ["threadId"]
+      },
+      handle: async (payload, emit, signal) => {
+        const threadId = readString(payload["threadId"]);
+        const push = () => {
+          void snapshot(ctx, store, threadId).then((value) => emit(value));
+        };
+        push();
+        const unsubscribe = store.subscribe(push);
+        try {
+          await abort(signal);
+        } finally {
+          unsubscribe();
+        }
+      }
+    });
+    ctx.settingsCard({
+      titleKey: "settings.card.title",
+      descriptionKey: "settings.card.description",
+      fields: []
+    });
+  }
+});
+function createService(ctx, store) {
+  return {
+    read: (threadId) => store.read(threadId),
+    update: (threadId, recipe) => store.update(threadId, recipe),
+    includeAuthorization: async () => (await store.prefs()).includeAuthorization,
+    publish: (threadId) => publish(ctx, store, threadId),
+    parentOf: (threadId) => parentOf(ctx, threadId)
+  };
+}
+async function publish(ctx, store, threadId) {
+  const engagement = await store.read(threadId);
+  const prefs = await store.prefs();
+  const mounted = engagement.goal !== null;
+  await ctx.sessionProjections.set({
+    name: MOUNTED_PROJECTION,
+    threadId,
+    value: mounted
+  });
+  await ctx.sessionProjections.set({
+    name: GRAPH_PROJECTION,
+    threadId,
+    value: mounted ? jsonValue(windowOf(engagement, prefs.windowLimit)) : null
+  });
+}
+async function snapshot(ctx, store, threadId) {
+  const engagement = threadId.length === 0 ? emptyEngagement() : await store.read(threadId);
+  const prefs = await store.prefs();
+  let related = [];
+  if (threadId.length > 0) {
+    try {
+      related = await relatedSessions(ctx.projections, threadId);
+    } catch (error) {
+      ctx.log.warn("pentest related sessions skipped", {
+        detail: error instanceof Error ? error.message : "unknown"
+      });
+    }
+  }
+  return {
+    mounted: engagement.goal !== null,
+    graph: engagement.goal === null ? null : windowOf(engagement, prefs.windowLimit),
+    related,
+    prefs,
+    report: reportMarkdown(engagement, prefs.includeAuthorization)
+  };
+}
+async function parentOf(ctx, threadId) {
+  const thread = await ctx.projections.getThread(threadId);
+  const parent = thread?.origin?.parentThreadId;
+  return parent === void 0 || parent.length === 0 ? null : parent;
+}
+function jsonValue(value) {
+  return JSON.parse(JSON.stringify(value));
+}
+function readString(value) {
+  return typeof value === "string" ? value : "";
+}
+function abort(signal) {
+  return new Promise((resolve) => {
+    if (signal.aborted) {
+      resolve();
+      return;
+    }
+    signal.addEventListener("abort", () => resolve(), { once: true });
+  });
+}
+var index_default = pentestPlugin;
+export {
+  index_default as default
+};