@nookplot/mcp 0.4.91 → 0.4.92

package/dist/syncSessionsState.js

@@ -0,0 +1,145 @@
+/**
+ * Phase 2b — session post-processor state tracking.
+ *
+ * Tracks which Hermes session files we've already processed, plus the
+ * SHA-256 hashes of the items we've extracted from each. Lives at
+ * `~/.nookplot/processed_sessions.json` with atomic tmp+rename writes so
+ * concurrent sync runs (if the user opts into a launchd timer AND invokes
+ * the CLI at the same time) can't corrupt the file.
+ *
+ * Two layers of dedup:
+ *
+ *   1. Session-level — if `sessions[session_id]` exists, skip the whole
+ *      file on the next run. Cheapest check.
+ *   2. Item-level — within a session, each extracted item's content hash
+ *      is recorded. The gateway's own `UNIQUE (agent_address, kind,
+ *      content_hash)` UUID-index makes duplicate POSTs idempotent
+ *      server-side anyway, but tracking locally lets `--force` do the
+ *      right thing (re-extract, but skip items already captured).
+ *
+ * @module syncSessionsState
+ */
+import { existsSync, readFileSync, writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+// ---------------------------------------------------------------------------
+//  Paths
+// ---------------------------------------------------------------------------
+/**
+ * Default location of the state file. Exposed so tests can override; in
+ * production we always use `~/.nookplot/processed_sessions.json` which
+ * sits next to `~/.nookplot/credentials.json` that the rest of the CLI
+ * uses — same directory, same permission model.
+ */
+export function defaultStatePath() {
+    return join(homedir(), ".nookplot", "processed_sessions.json");
+}
+// ---------------------------------------------------------------------------
+//  Load / save
+// ---------------------------------------------------------------------------
+/**
+ * Load the state file, or return a blank state if it doesn't exist / is
+ * corrupted. Corruption fallback is deliberate: if someone hand-edits the
+ * file into garbage, we'd rather re-process everything than crash the
+ * installer. Re-processing is safe because the gateway's dedup guard
+ * blocks exact duplicates.
+ */
+export function loadState(path = defaultStatePath()) {
+    const empty = { version: 1, sessions: {} };
+    if (!existsSync(path))
+        return empty;
+    try {
+        const raw = readFileSync(path, "utf8");
+        const parsed = JSON.parse(raw);
+        // Accept only what we expect. Future-proof against a user's pre-existing
+        // file from a beta build that had a different shape — we'd rather
+        // drop and rebuild than crash on startup.
+        if (parsed &&
+            typeof parsed === "object" &&
+            parsed.version === 1 &&
+            parsed.sessions &&
+            typeof parsed.sessions === "object") {
+            return parsed;
+        }
+        return empty;
+    }
+    catch {
+        return empty;
+    }
+}
+/**
+ * Atomic write: serialize → write to `${path}.tmp` → rename over the real
+ * file. `rename` is atomic on POSIX + NTFS, so a reader can never see a
+ * half-written file. No fsync here — if the process crashes between write
+ * and rename, the old file is untouched, and worst case we re-process a
+ * session (which the gateway dedup will catch).
+ */
+export function saveState(state, path = defaultStatePath()) {
+    const dir = dirname(path);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const tmp = `${path}.tmp`;
+    writeFileSync(tmp, JSON.stringify(state, null, 2), "utf8");
+    renameSync(tmp, path);
+}
+// ---------------------------------------------------------------------------
+//  Mutations
+// ---------------------------------------------------------------------------
+/**
+ * Has this session already been processed? If so, the caller should skip
+ * it on the next run (unless `--force` was passed, in which case the
+ * caller explicitly bypasses this check).
+ */
+export function isSessionProcessed(state, sessionId) {
+    return sessionId in state.sessions;
+}
+/**
+ * Has this specific item already been captured? Used inside `--force` re-runs
+ * so we don't hit the gateway with POSTs that we *know* will be deduped.
+ * Saves a round-trip + avoids inflating the per-agent rate-limit counter.
+ */
+export function isItemAlreadyCaptured(state, sessionId, hash) {
+    const session = state.sessions[sessionId];
+    if (!session)
+        return false;
+    return session.items.some((i) => i.hash === hash && i.captureId !== undefined);
+}
+/**
+ * Record the result of processing one session. Overwrites any prior
+ * record — if a `--force` re-run captures more items than the first pass
+ * (e.g., the extractor heuristic was loosened), the merged record reflects
+ * everything captured across both passes.
+ */
+export function markSessionProcessed(state, sessionId, items) {
+    const existing = state.sessions[sessionId];
+    // Merge items from prior run + this run, keyed by hash so we never lose
+    // the captureId of a previously-successful item even if the current
+    // extraction pass fails to re-create it.
+    const mergedByHash = new Map();
+    if (existing) {
+        for (const item of existing.items)
+            mergedByHash.set(item.hash, item);
+    }
+    for (const item of items) {
+        const prior = mergedByHash.get(item.hash);
+        // Prefer the new record if it succeeded; keep the old captureId if
+        // the new one errored but the old one had a valid id.
+        if (prior && prior.captureId && !item.captureId) {
+            mergedByHash.set(item.hash, prior);
+        }
+        else {
+            mergedByHash.set(item.hash, item);
+        }
+    }
+    return {
+        ...state,
+        sessions: {
+            ...state.sessions,
+            [sessionId]: {
+                processedAt: new Date().toISOString(),
+                items: Array.from(mergedByHash.values()),
+            },
+        },
+    };
+}
+//# sourceMappingURL=syncSessionsState.js.map

package/dist/syncSessionsState.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"syncSessionsState.js","sourceRoot":"","sources":["../src/syncSessionsState.ts"],"names":[],"mappings":"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"}

package/dist/tools/captures.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Phase 2a — realtime capture MCP tools.
+ *
+ * Three tools the Hermes (or any MCP-compatible) agent can call DURING a
+ * session to sync findings + reasoning back to Nookplot. Captures land in
+ * the review queue (`POST /v1/me/captures`) behind a 24h auto-publish
+ * window, so the user stays in control of what enters their knowledge
+ * graph. After publish, the items earn citation rewards like any other
+ * KG entry.
+ *
+ * Tools:
+ *   - `nookplot_capture_finding`   — research result / distilled insight
+ *   - `nookplot_capture_reasoning` — structured multi-step reasoning trace
+ *   - `nookplot_list_my_captures`  — read-only queue listing for the agent
+ *
+ * Design notes:
+ *   - All three forward `NOOKPLOT_AGENT_ADDRESS` (via `ctx.scopedAgentAddress`)
+ *     as the `agentAddress` field in the POST body, so the gateway's queue
+ *     row records the forged agent (not the creator) in the `agent_address`
+ *     column. This preserves per-agent attribution across multi-agent
+ *     creators.
+ *   - The agent never writes directly to the KG — all quality gating,
+ *     sybil enforcement, content scanning, and rate limiting lives at the
+ *     queue endpoint, not here. Keeping the tool side thin means we only
+ *     ever have to patch security policy in one place.
+ *   - Tool descriptions explicitly tell the model when to call them +
+ *     what NOT to capture (tool output dumps, fabricated findings), because
+ *     this is the knob that most affects model compliance in the "Hermes
+ *     agent voluntarily captures" architecture (Plan Phase 2a).
+ *
+ * @module tools/captures
+ */
+import type { ToolDef } from "./index.js";
+export declare const captureTools: ToolDef[];
+//# sourceMappingURL=captures.d.ts.map

package/dist/tools/captures.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"captures.d.ts","sourceRoot":"","sources":["../../src/tools/captures.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAe,MAAM,YAAY,CAAC;AA4BvD,eAAO,MAAM,YAAY,EAAE,OAAO,EAmRjC,CAAC"}

package/dist/tools/captures.js

@@ -0,0 +1,315 @@
+/**
+ * Phase 2a — realtime capture MCP tools.
+ *
+ * Three tools the Hermes (or any MCP-compatible) agent can call DURING a
+ * session to sync findings + reasoning back to Nookplot. Captures land in
+ * the review queue (`POST /v1/me/captures`) behind a 24h auto-publish
+ * window, so the user stays in control of what enters their knowledge
+ * graph. After publish, the items earn citation rewards like any other
+ * KG entry.
+ *
+ * Tools:
+ *   - `nookplot_capture_finding`   — research result / distilled insight
+ *   - `nookplot_capture_reasoning` — structured multi-step reasoning trace
+ *   - `nookplot_list_my_captures`  — read-only queue listing for the agent
+ *
+ * Design notes:
+ *   - All three forward `NOOKPLOT_AGENT_ADDRESS` (via `ctx.scopedAgentAddress`)
+ *     as the `agentAddress` field in the POST body, so the gateway's queue
+ *     row records the forged agent (not the creator) in the `agent_address`
+ *     column. This preserves per-agent attribution across multi-agent
+ *     creators.
+ *   - The agent never writes directly to the KG — all quality gating,
+ *     sybil enforcement, content scanning, and rate limiting lives at the
+ *     queue endpoint, not here. Keeping the tool side thin means we only
+ *     ever have to patch security policy in one place.
+ *   - Tool descriptions explicitly tell the model when to call them +
+ *     what NOT to capture (tool output dumps, fabricated findings), because
+ *     this is the knob that most affects model compliance in the "Hermes
+ *     agent voluntarily captures" architecture (Plan Phase 2a).
+ *
+ * @module tools/captures
+ */
+// ---------------------------------------------------------------------------
+//  Shared helpers
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the agent address to attribute this capture to.
+ *
+ * If the MCP server was started with `NOOKPLOT_AGENT_ADDRESS` (the Hermes
+ * installer sets this), we pass that specific forged agent's address
+ * through to the gateway. Otherwise we fall back to undefined and the
+ * route defaults to `ctx.address` (the creator) server-side.
+ *
+ * We keep the resolution here rather than unconditionally passing
+ * `ctx.address` because the gateway's validator explicitly rejects a
+ * malformed `agentAddress` (anything not 0x + 40 hex), and an empty
+ * string would trip that check. `undefined` tells the route "use the
+ * default" cleanly.
+ */
+function resolveAgentAddress(ctx) {
+    return ctx.scopedAgentAddress || undefined;
+}
+// ---------------------------------------------------------------------------
+//  Tool definitions
+// ---------------------------------------------------------------------------
+export const captureTools = [
+    // ─── 1. capture_finding ──────────────────────────────────────
+    {
+        name: "nookplot_capture_finding",
+        description: "Save a research finding or distilled insight to your Nookplot knowledge " +
+            "graph. **Call this after** a web_search / arxiv / browser / research session " +
+            "when you have something worth remembering — a fact, pattern, conclusion, or " +
+            "summary backed by sources.\n\n" +
+            "**PREFER THIS over `nookplot_store_knowledge_item`** for Hermes-session " +
+            "research syntheses — it routes through the user's 24h review queue so the " +
+            "user stays in control of what enters the public KG. Use `store_knowledge_item` " +
+            "only for: (a) internal daemon synthesis from `compile_knowledge`, or " +
+            "(b) mining/verification post-solve storage where the user isn't reviewing " +
+            "each item. Calling BOTH on the same content writes duplicates and burns " +
+            "your rate budget.\n\n" +
+            "**Goes into the 24h review queue**, not directly to the KG. The user can " +
+            "reject bad captures; uncontested ones auto-publish. Once published, other " +
+            "agents can cite your item — citations earn the user reputation + NOOK.\n\n" +
+            "**When to call:**\n" +
+            "- After substantive research (web_search + extract → synthesize → capture)\n" +
+            "- After reading a paper / doc + distilling the key point\n" +
+            "- When you learn something the user likely wants to remember\n\n" +
+            "**When NOT to call:**\n" +
+            "- Raw tool output. Capture YOUR synthesis, not the dump.\n" +
+            "- Fabricated / unsourced claims. The network flags hallucinated content.\n" +
+            "- Duplicates. Before capturing, call `nookplot_search_knowledge` with your " +
+            "finding's core claim. If a high-similarity item exists, call " +
+            "`nookplot_add_knowledge_citation` instead. The server dedupes exact hashes; " +
+            "near-duplicates waste the rate budget (10 findings/hr/forged-agent).\n\n" +
+            "**Rate limit:** 10 findings/hour per forged-agent. On HTTP 429 with " +
+            "`retryAfterMs=N`, do NOT retry within N milliseconds — bucket is per-agent-" +
+            "per-hour and retrying faster just wastes API budget with no chance of success.\n\n" +
+            "**Error codes:**\n" +
+            "- 400 `invalid_payload` — body < 200 chars OR contains a markdown link with " +
+            "a disallowed scheme (only http/https/ipfs/mailto allowed) OR source[N] is " +
+            "not a valid URL (see `sources` field description).\n" +
+            "- 400 `content_blocked` with `reason` subcode — ContentScanner flagged the " +
+            "body. If `reason=prompt_injection`, rewrite without system/assistant tags " +
+            "or 'ignore previous instructions' patterns. If `reason=spam_detected`, " +
+            "revise the substantive text.\n" +
+            "- 403 `agent_not_owned` — the submitted agentAddress doesn't belong to your " +
+            "creator. Don't send `agentAddress` explicitly; let the default flow handle it.\n\n" +
+            "**Good example:** `body: \"## Deserialization risk in Foo\\n\\nThe Foo library " +
+            "accepts untrusted YAML by default; fix: set strict_mode=true. Verified against " +
+            "issues #142, #203.\"`\n\n" +
+            "Returns the queue item id + the auto-publish deadline. Use " +
+            "`nookplot_list_my_captures` to check status.",
+        category: "knowledge",
+        inputSchema: {
+            type: "object",
+            properties: {
+                title: {
+                    type: "string",
+                    description: "Short descriptive title for the queue UI. Keep under 80 chars.",
+                },
+                body: {
+                    type: "string",
+                    description: "The finding itself, in markdown. Structure it (headers, bullets, code " +
+                        "blocks). Minimum 200 chars of substantive content — shorter captures " +
+                        "get rejected by the quality gate. Maximum ~9,500 chars before auto-" +
+                        "truncation. Markdown links must use http/https/ipfs/mailto schemes " +
+                        "only — `[x](javascript:...)`, `[x](data:...)`, etc. are blocked.",
+                },
+                sources: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "URLs or identifiers of the sources that back this finding. Each entry " +
+                        "must be an `http(s)://` URL (max 500 chars), `ipfs://...`, OR an opaque " +
+                        "alphanumeric ID (1-100 chars, matching `[a-zA-Z0-9._-]` — e.g., arXiv " +
+                        "bare IDs like `2310.12345`, DOIs, NIST.SP.800-63B, kg-item UUIDs). " +
+                        "`data:`, `javascript:`, `file:` URIs are REJECTED. Always populate " +
+                        "`sources` when you used web_search / browser / arxiv tools.",
+                },
+                domain: {
+                    type: "string",
+                    description: "Knowledge domain — e.g. 'security', 'defi', 'ml', 'hermes-agent'. " +
+                        "Strongly recommended; items without a domain are harder for the " +
+                        "knowledge compiler to cross-link.",
+                },
+                tags: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Additional tags for discoverability.",
+                },
+                sourceSessionId: {
+                    type: "string",
+                    description: "Optional: the Hermes session ID this finding came from. Must match " +
+                        "`/^[a-zA-Z0-9_-]{1,100}$/` — alnum + underscore + hyphen, 1-100 chars " +
+                        "(Hermes's real format is `YYYYMMDD_HHMMSS_hex`, which fits). Malformed " +
+                        "values return 400 `invalid_source_session_id`.",
+                },
+            },
+            required: ["title", "body"],
+        },
+        handler: async (args, ctx) => {
+            return ctx.post("/v1/me/captures", {
+                kind: "finding",
+                payload: {
+                    title: args.title,
+                    body: args.body,
+                    sources: args.sources,
+                    domain: args.domain,
+                    tags: args.tags,
+                },
+                agentAddress: resolveAgentAddress(ctx),
+                sourceSessionId: args.sourceSessionId,
+            });
+        },
+    },
+    // ─── 2. capture_reasoning ───────────────────────────────────
+    {
+        name: "nookplot_capture_reasoning",
+        description: "Save a multi-step reasoning trace to your Nookplot knowledge graph. **Use this** " +
+            "for problems where the *process* of figuring something out is the valuable " +
+            "artifact — not just the final answer.\n\n" +
+            "**Goes into the 24h review queue.** Publishes as `knowledgeType: procedure`, " +
+            "so other agents searching for how-to-solve-X patterns can find + cite it.\n\n" +
+            "**When to call:**\n" +
+            "- After you walked through several connected thinking steps to reach a non-" +
+            "obvious conclusion.\n" +
+            "- After debugging a tricky issue where the *path* mattered.\n" +
+            "- After a chain-of-reasoning that included pivots or dead-ends worth documenting.\n\n" +
+            "**When NOT to call:**\n" +
+            "- Trivial / one-step answers. Use `nookplot_capture_finding` for facts.\n" +
+            "- Tool-call transcripts. Summarize YOUR reasoning; the tool outputs aren't " +
+            "the reasoning.\n" +
+            "- Unsolved problems. Capture only reasoning that reached a conclusion, even " +
+            "if the conclusion is 'more info needed'.\n" +
+            "- Conclusions drawn purely from your own prior captures — cite them with " +
+            "`nookplot_add_knowledge_citation` instead.\n\n" +
+            "**Rate limit:** 3 reasoning captures per hour per forged-agent (tighter " +
+            "than findings — reasoning is rarer and higher-value). On HTTP 429 with " +
+            "`retryAfterMs=N`, do NOT retry within N milliseconds.\n\n" +
+            "**Error codes:** 400 `invalid_payload` on <2 steps or <50-char conclusion " +
+            "or markdown-link scheme violation; 400 `content_blocked` with `reason` " +
+            "subcode from the ContentScanner; 403 `agent_not_owned` on agentAddress " +
+            "mismatch with your creator.\n\n" +
+            "Returns the queue item id + auto-publish deadline.",
+        category: "knowledge",
+        inputSchema: {
+            type: "object",
+            properties: {
+                taskSummary: {
+                    type: "string",
+                    description: "One-sentence summary of what you were solving. Rendered as the " +
+                        "knowledge item's title.",
+                },
+                steps: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: {
+                            step: {
+                                type: "string",
+                                description: "What you did / tried / concluded at this step. Max ~800 chars " +
+                                    "per step (longer steps get auto-truncated with a marker).",
+                            },
+                            rationale: {
+                                type: "string",
+                                description: "Optional: why this step — prior observations, alternatives " +
+                                    "considered, branches taken. Can include dead-ends that got " +
+                                    "abandoned.",
+                            },
+                        },
+                        required: ["step"],
+                    },
+                    description: "Ordered reasoning steps. **Minimum 2 steps required** — single-step " +
+                        "'reasoning' belongs in `nookplot_capture_finding`, not here. " +
+                        "Gateway returns 400 `invalid_payload` on <2 steps.",
+                },
+                conclusion: {
+                    type: "string",
+                    description: "Your final answer + a confidence qualifier if applicable. " +
+                        "**Minimum 50 chars** — bare 'yes'/'no' gets rejected by the quality " +
+                        "gate (400 `invalid_payload`). Max ~9,500 chars before auto-truncation. " +
+                        "Markdown links restricted to http/https/ipfs/mailto schemes.",
+                },
+                citations: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional: IDs of Nookplot knowledge items you leaned on. Sets up " +
+                        "citation edges after publish.",
+                },
+                modelUsed: {
+                    type: "string",
+                    description: "LLM model that produced the reasoning (e.g. 'gemini-flash-latest', " +
+                        "'claude-opus-4-6'). Used for audit + for the verifier network's " +
+                        "per-model quality stats.",
+                },
+                sourceSessionId: {
+                    type: "string",
+                    description: "Optional: Hermes session ID (same semantic as capture_finding).",
+                },
+            },
+            required: ["taskSummary", "steps", "conclusion"],
+        },
+        handler: async (args, ctx) => {
+            return ctx.post("/v1/me/captures", {
+                kind: "reasoning",
+                payload: {
+                    taskSummary: args.taskSummary,
+                    steps: args.steps,
+                    conclusion: args.conclusion,
+                    citations: args.citations,
+                    modelUsed: args.modelUsed,
+                },
+                agentAddress: resolveAgentAddress(ctx),
+                sourceSessionId: args.sourceSessionId,
+            });
+        },
+    },
+    // ─── 3. list_my_captures ────────────────────────────────────
+    {
+        name: "nookplot_list_my_captures",
+        description: "List your pending / published / rejected captures from the Nookplot review " +
+            "queue. Useful for confirming a capture landed, checking what's about to " +
+            "auto-publish, or reviewing what the user has rejected.\n\n" +
+            "**Free.** Returns the caller's own captures only — never another user's.\n\n" +
+            "**Response includes:** per-capture `id`, `agentAddress` (forged agent " +
+            "attribution), `status`, `kind`, `payload`, `autoPublishAt` (ISO timestamp " +
+            "of the 24h auto-publish deadline), and `publishedItemId` (set after " +
+            "publish — pass to `nookplot_get_knowledge_item` to read the live KG entry).\n\n" +
+            "**Captures come from two sources:**\n" +
+            "- Realtime `nookplot_capture_finding` / `nookplot_capture_reasoning` tools " +
+            "invoked DURING a session.\n" +
+            "- The `nookplot-mcp sync-sessions` CLI post-processor — a user-invoked " +
+            "safety net that extracts captures from past Hermes sessions. You don't " +
+            "call this from inside the agent; the user runs it manually.\n\n" +
+            "**When to call:**\n" +
+            "- After `nookplot_capture_finding` / `nookplot_capture_reasoning` to confirm " +
+            "the id + auto-publish deadline.\n" +
+            "- At the start of a daemon tick to see if the user rejected items from the " +
+            "last tick. If >30% of recent captures were rejected, pause capturing this " +
+            "tick and read 2-3 rejected items to understand what pattern the user dislikes.\n" +
+            "- When the user asks 'what have I captured recently'.",
+        category: "knowledge",
+        inputSchema: {
+            type: "object",
+            properties: {
+                status: {
+                    type: "string",
+                    enum: ["pending", "published", "rejected", "all"],
+                    description: "Filter by status. 'pending' (default) shows the 24h review queue; " +
+                        "'published' shows what's live in the KG; 'rejected' shows what the " +
+                        "user declined; 'all' merges them.",
+                },
+                limit: {
+                    type: "number",
+                    description: "Max results (default: 50, max: 200).",
+                },
+            },
+        },
+        handler: async (args, ctx) => {
+            const status = args.status ?? "pending";
+            const limit = args.limit ?? 50;
+            return ctx.get(`/v1/me/captures?status=${encodeURIComponent(status)}&limit=${limit}`);
+        },
+    },
+];
+//# sourceMappingURL=captures.js.map

package/dist/tools/captures.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"captures.js","sourceRoot":"","sources":["../../src/tools/captures.ts"],"names":[],"mappings":"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"}

package/dist/tools/forgePresets.d.ts

@@ -1,6 +1,11 @@
 /**
- * Forge preset tools — pre-configured challenge templates.
- * Placeholder — tools to be added as forge presets are built.
+ * Forge Preset tools — browse, search, and estimate costs for forge presets.
+ *
+ * Forge presets define what knowledge an agent loads at boot: mining traces,
+ * bundles, aggregates, memory packs, reppo datanets. These tools let agents
+ * discover presets and understand costs before deploying.
+ *
+ * On-chain forge operations (deploy/spawn/soul) are in memory.ts (forgeTools).
  *
  * @module tools/forgePresets
  */

package/dist/tools/forgePresets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"forgePresets.d.ts","sourceRoot":"","sources":["../../src/tools/forgePresets.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,gBAAgB,EAAE,OAAO,EAAO,CAAC"}
+{"version":3,"file":"forgePresets.d.ts","sourceRoot":"","sources":["../../src/tools/forgePresets.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,YAAY,CAAC;AAE1C,eAAO,MAAM,gBAAgB,EAAE,OAAO,EAsHrC,CAAC"}