npm - @binarycheater/research-sidecar - Versions diffs - 0.1.0 - Mend

@binarycheater/research-sidecar 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (92) hide show

package/dist/client/index.html ADDED Viewed

@@ -0,0 +1,13 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Research Sidecar</title>
+    <script type="module" crossorigin src="/assets/index-D7VDrQ1Q.js"></script>
+    <link rel="stylesheet" crossorigin href="/assets/index-BpVgCKdz.css">
+  </head>
+  <body>
+    <div id="root"></div>
+  </body>
+</html>

package/dist-server/lib/context.js ADDED Viewed

@@ -0,0 +1,70 @@
+export function buildContextPacket(input) {
+    const files = input.files.length
+        ? input.files
+            .map((file) => `### File: ${file.path}
+Bytes: ${file.bytes}
+Added: ${file.addedAt}
+${file.content}`)
+            .join("\n\n---\n\n")
+        : "No file snapshots were attached.";
+    const history = input.history.length
+        ? input.history
+            .map((message) => `${roleLabel(message.role)}: ${message.content}`)
+            .join("\n\n")
+        : "No prior messages in this session.";
+    const instructions = input.instructionFiles.length
+        ? input.instructionFiles.map((file) => `### ${file.path}\n\n${file.content}`).join("\n\n---\n\n")
+        : "Instruction files were not included.";
+    const skills = input.workspaceSkills.length
+        ? input.workspaceSkills.map((skill) => `- ${skill.name}: ${skill.description} (${skill.path})`).join("\n")
+        : "No workspace skills were discovered.";
+    const triggered = input.skillTriggers.length
+        ? input.skillTriggers
+            .map((trigger) => `- ${trigger.skill.name}: ${trigger.confidence} confidence, ${trigger.disclosure}. ${trigger.reason} (${trigger.skill.path})`)
+            .join("\n")
+        : "No workspace skill appears directly triggered by this turn.";
+    const loadedSkills = input.loadedSkillFiles.length
+        ? input.loadedSkillFiles.map((file) => `### Loaded Skill: ${file.path}\n\n${file.content}`).join("\n\n---\n\n")
+        : "No full skill instructions were auto-loaded. If a candidate skill seems relevant, use the load_skill tool before relying on it.";
+    return `${input.reviewPrompt}
+## Explicit Context Packet
+### Manual Context
+${input.manualContext.trim() || "No manual context was supplied."}
+### Instruction Files
+${instructions}
+### Workspace Skills
+${skills}
+### Triggered Skills For This Turn
+${triggered}
+### Loaded Skill Instructions
+${loadedSkills}
+### File Snapshots
+${files}
+### Conversation History
+${history}
+### Current User Request
+${input.userMessage.trim()}
+## Response Constraints
+Only use the explicit context above. The stable protocol, manual context, and file snapshots are intentionally placed before conversation history and the current request so providers with prompt/context caching can reuse the longest unchanged prefix. If a judgment depends on hidden Codex context, say what is missing instead of guessing.`;
+}
+function roleLabel(role) {
+    if (role === "assistant")
+        return "Assistant";
+    if (role === "tool")
+        return "Tool";
+    if (role === "system")
+        return "System";
+    return "User";
+}

package/dist-server/lib/files.js ADDED Viewed

@@ -0,0 +1,118 @@
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, normalize, relative, resolve, sep } from "node:path";
+const MAX_FILE_BYTES = 512_000;
+const CODE_EXTENSIONS = new Set([
+    ".c",
+    ".cc",
+    ".cpp",
+    ".cs",
+    ".go",
+    ".java",
+    ".js",
+    ".jsx",
+    ".mjs",
+    ".py",
+    ".rb",
+    ".rs",
+    ".sh",
+    ".swift",
+    ".ts",
+    ".tsx"
+]);
+export function resolveWorkspacePath(workspaceRoot, requestedPath) {
+    if (!requestedPath.trim()) {
+        throw new Error("Path is required.");
+    }
+    if (isAbsolute(requestedPath)) {
+        throw new Error("Use a path relative to the workspace root.");
+    }
+    const root = resolve(workspaceRoot);
+    const target = resolve(root, requestedPath);
+    const rel = relative(root, target);
+    if (rel === "" || rel.startsWith("..") || rel.includes(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error("Requested path is outside the workspace.");
+    }
+    return target;
+}
+export function toWorkspaceRelativePath(workspaceRoot, fullPath) {
+    const root = resolve(workspaceRoot);
+    const target = resolve(fullPath);
+    const rel = relative(root, target);
+    if (rel === "" || rel.startsWith("..") || rel.includes(`..${sep}`) || isAbsolute(rel)) {
+        throw new Error("Requested path is outside the workspace.");
+    }
+    return rel.split(sep).join("/");
+}
+export function resolveWorkspaceRelativeLink(basePath, href) {
+    const cleanHref = href.trim();
+    if (!cleanHref || cleanHref.startsWith("#") || /^[a-z][a-z0-9+.-]*:/i.test(cleanHref) || cleanHref.startsWith("//")) {
+        return null;
+    }
+    const [pathPart, suffix = ""] = splitLinkSuffix(cleanHref);
+    if (!pathPart)
+        return null;
+    const baseDir = dirname(basePath);
+    const next = normalize(join(baseDir, pathPart)).split(sep).join("/");
+    if (next === "." || next.startsWith("../") || next === "..") {
+        return null;
+    }
+    return `${next}${suffix}`;
+}
+export async function readWorkspaceFile(workspaceRoot, requestedPath) {
+    const fullPath = resolveWorkspacePath(workspaceRoot, requestedPath);
+    const info = await stat(fullPath);
+    if (!info.isFile()) {
+        throw new Error("Requested path is not a file.");
+    }
+    if (info.size > MAX_FILE_BYTES) {
+        throw new Error(`File is too large for the sidecar snapshot (${info.size} bytes).`);
+    }
+    const content = await readFile(fullPath, "utf8");
+    return {
+        id: crypto.randomUUID(),
+        path: requestedPath,
+        content,
+        bytes: Buffer.byteLength(content),
+        ...detectFilePreviewFormat(requestedPath),
+        addedAt: new Date().toISOString()
+    };
+}
+export async function writeWorkspaceFile(workspaceRoot, requestedPath, content, allowedExtensions) {
+    assertWritableWorkspacePath(requestedPath, allowedExtensions);
+    const fullPath = resolveWorkspacePath(workspaceRoot, requestedPath);
+    await mkdir(dirname(fullPath), { recursive: true });
+    await writeFile(fullPath, content, "utf8");
+    return {
+        path: requestedPath,
+        bytes: Buffer.byteLength(content)
+    };
+}
+export function detectFilePreviewFormat(path) {
+    const extension = extname(path).toLowerCase();
+    if (extension === ".md" || extension === ".markdown") {
+        return { format: "markdown", mimeType: "text/markdown" };
+    }
+    if (extension === ".html" || extension === ".htm") {
+        return { format: "html", mimeType: "text/html" };
+    }
+    return { format: "text", mimeType: "text/plain" };
+}
+function assertWritableWorkspacePath(path, allowedExtensions) {
+    const extension = extname(path).toLowerCase();
+    if (CODE_EXTENSIONS.has(extension)) {
+        throw new Error(`Writing code files is not allowed (${extension}).`);
+    }
+    const normalized = allowedExtensions.map((item) => (item.startsWith(".") ? item : `.${item}`).toLowerCase());
+    if (!normalized.includes(extension)) {
+        throw new Error(`Writing ${extension || "extensionless"} files is not allowed. Allowed extensions: ${normalized.join(", ")}.`);
+    }
+}
+function splitLinkSuffix(href) {
+    const hashIndex = href.indexOf("#");
+    const queryIndex = href.indexOf("?");
+    const candidates = [hashIndex, queryIndex].filter((index) => index >= 0);
+    if (!candidates.length)
+        return [href, ""];
+    const index = Math.min(...candidates);
+    return [href.slice(0, index), href.slice(index)];
+}

package/dist-server/lib/graphDiscovery.js ADDED Viewed

@@ -0,0 +1,69 @@
+import { readdir } from "node:fs/promises";
+import { join, relative, resolve, sep } from "node:path";
+import { loadResearchGraphManifest } from "./researchGraphManifest.js";
+const IGNORED_DIRECTORIES = new Set([".git", ".hg", ".side", ".next", ".turbo", "coverage", "dist", "dist-server", "node_modules"]);
+const GRAPH_FILE_PATTERN = /(^graph|\.graph)\.ya?ml$/i;
+export async function discoverGraphManifests(workspaceRoot, selectedPath) {
+    const root = resolve(workspaceRoot);
+    const paths = await findGraphManifestPaths(root);
+    const candidates = await Promise.all(paths.map((path) => describeGraphManifest(root, path, selectedPath)));
+    return candidates.sort((left, right) => {
+        if (left.selected !== right.selected)
+            return left.selected ? -1 : 1;
+        return left.path.localeCompare(right.path);
+    });
+}
+async function describeGraphManifest(workspaceRoot, path, selectedPath) {
+    const selected = normalizePath(path) === normalizePath(selectedPath || "");
+    try {
+        const graph = await loadResearchGraphManifest(workspaceRoot, path);
+        const rootNode = graph.nodes.find((node) => node.id === graph.rootId);
+        return {
+            path,
+            selected,
+            rootId: graph.rootId,
+            title: rootNode?.title,
+            nodeCount: graph.nodes.length,
+            edgeCount: graph.edges.length
+        };
+    }
+    catch (error) {
+        return {
+            path,
+            selected,
+            error: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+async function findGraphManifestPaths(root, dir = "") {
+    const fullDir = join(root, dir);
+    let entries;
+    try {
+        entries = await readdir(fullDir, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+    const out = [];
+    for (const entry of entries) {
+        if (entry.name.startsWith(".") && entry.name !== ".research") {
+            if (IGNORED_DIRECTORIES.has(entry.name))
+                continue;
+        }
+        const rel = dir ? `${dir}/${entry.name}` : entry.name;
+        if (entry.isDirectory()) {
+            if (IGNORED_DIRECTORIES.has(entry.name))
+                continue;
+            out.push(...(await findGraphManifestPaths(root, rel)));
+        }
+        else if (entry.isFile() && GRAPH_FILE_PATTERN.test(entry.name)) {
+            out.push(normalizePath(relative(root, join(root, rel))));
+        }
+    }
+    return out;
+}
+function normalizePath(path) {
+    return path.split(sep).join("/").replace(/^\.\//, "").replace(/^\/+/, "");
+}

package/dist-server/lib/openaiProvider.js ADDED Viewed

@@ -0,0 +1,89 @@
+import OpenAI from "openai";
+import { createWorkspaceTools } from "./tools.js";
+const MAX_TOOL_ITERATIONS = 6;
+export async function streamOpenAIReview(input) {
+    const client = new OpenAI({ apiKey: input.apiKey, baseURL: input.baseURL });
+    if (input.apiMode === "chat") {
+        await runChatCompletion(input, client);
+        return;
+    }
+    if (input.enableTools) {
+        throw new Error("Tool use is only available in chat mode.");
+    }
+    const stream = await client.responses.create({
+        model: input.model,
+        stream: true,
+        input: input.contextPacket
+    }, { signal: input.signal });
+    for await (const event of stream) {
+        if (event.type === "response.output_text.delta") {
+            input.onDelta(event.delta);
+        }
+    }
+}
+async function runChatCompletion(input, client) {
+    if (!input.enableTools) {
+        await streamFinalChatAnswer(client, input, [{ role: "user", content: input.contextPacket }]);
+        return;
+    }
+    const messages = [{ role: "user", content: input.contextPacket }];
+    const tools = createWorkspaceTools(input.workspaceRoot, { allowedWriteExtensions: input.allowedWriteExtensions });
+    for (let i = 0; i < MAX_TOOL_ITERATIONS; i += 1) {
+        const response = await client.chat.completions.create({
+            model: input.model,
+            stream: false,
+            messages,
+            tools: tools.definitions,
+            tool_choice: "auto"
+        }, { signal: input.signal });
+        const message = response.choices[0]?.message;
+        if (!message)
+            return;
+        messages.push(message);
+        if (!message.tool_calls?.length) {
+            input.onDelta(message.content || "");
+            return;
+        }
+        for (const toolCall of message.tool_calls) {
+            if (toolCall.type !== "function") {
+                continue;
+            }
+            const name = toolCall.function.name;
+            const args = toolCall.function.arguments || "{}";
+            input.onToolCall?.(name, args);
+            const result = truncateToolResult(String(await tools.execute(name, args)));
+            input.onToolResult?.(name, result);
+            messages.push({
+                role: "tool",
+                tool_call_id: toolCall.id,
+                content: result
+            });
+        }
+    }
+    await streamFinalChatAnswer(client, input, [
+        ...messages,
+        {
+            role: "system",
+            content: "The workspace tool-call limit has been reached. Stop calling tools and answer from the evidence already gathered. If the evidence is insufficient, say exactly what is missing."
+        }
+    ]);
+}
+async function streamFinalChatAnswer(client, input, messages) {
+    const stream = await client.chat.completions.create({
+        model: input.model,
+        stream: true,
+        messages
+    }, { signal: input.signal });
+    for await (const event of stream) {
+        const delta = event.choices[0]?.delta?.content;
+        if (delta) {
+            input.onDelta(delta);
+        }
+    }
+}
+function truncateToolResult(value) {
+    if (value.length <= 20_000) {
+        return value;
+    }
+    return `${value.slice(0, 20_000)}\n\n[Tool result truncated at 20000 characters.]`;
+}

package/dist-server/lib/prompt.js ADDED Viewed

@@ -0,0 +1,30 @@
+export const DEFAULT_MODEL = "gpt-5.5";
+export const DEFAULT_REVIEW_PROMPT = `# Sidecar Thinking
+Act as an independent research and engineering thinking partner. Use only the explicit context packet, attached instruction files, discovered skills, tool results, and conversation history. Do not pretend to know Codex's hidden state.
+Style:
+- Be direct, concise, and conceptually precise.
+- Lead with the actual judgment or answer, not with process.
+- Separate facts, inferences, assumptions, value judgments, and missing context.
+- Challenge weak evidence without being performative.
+- Prefer rival explanations and concrete falsifiers over generic pros/cons.
+- Do not force a rigid template when a short answer is better.
+Skills:
+- Workspace skills are discovered from SKILL.md frontmatter and listed in the context packet.
+- High-confidence skill matches have their full SKILL.md instructions auto-loaded. Treat those loaded instructions as guidance for this turn.
+- Medium-confidence skill matches are candidates only. If one seems relevant, call load_skill before relying on its full workflow.
+- If a skill is triggered or loaded, mention briefly which skill influenced the answer when that matters to the user.
+- Do not treat skill names as magic. Follow the substance of the relevant skill.
+Tools:
+- Use workspace tools when the answer depends on files, git diff, or available workspace structure.
+- Use load_skill when a candidate workspace skill may apply but its full instructions were not loaded.
+- Prefer reading/listing only what is needed. Do not browse the entire tree unless the user asks for broad inventory.
+- When multiple files are likely needed, use read_workspace_files once instead of repeated read_workspace_file calls.
+- Stop gathering files once you have enough evidence to answer; if the remaining context is missing, state the gap instead of continuing tool calls.
+- Report tool calls and results plainly in the conversation flow.
+- If tools are unavailable or insufficient, say what context is missing.
+For non-trivial reviews, a useful shape is: conclusion, basis, weakest assumption, next evidence or action. Use Markdown naturally.`;

package/dist-server/lib/researchGraph.js ADDED Viewed

@@ -0,0 +1,144 @@
+const hierarchyEdgeKinds = new Set(["decomposes", "answers", "operationalizes", "leads_to"]);
+export function buildGraphIndex(graph) {
+    const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+    return {
+        nodes: graph.nodes,
+        byId,
+        search(query) {
+            const normalized = normalize(query);
+            if (!normalized)
+                return graph.nodes;
+            return graph.nodes.filter((node) => searchableNodeText(node).includes(normalized));
+        }
+    };
+}
+export function getVisibleResearchGraph(graph, options) {
+    const byId = new Map(graph.nodes.map((node) => [node.id, node]));
+    const hierarchyEdges = graph.edges.filter((edge) => hierarchyEdgeKinds.has(edge.kind));
+    const childrenByParent = groupEdges(hierarchyEdges, "from");
+    const parentsByChild = groupEdges(hierarchyEdges, "to");
+    const childCounts = Object.fromEntries(graph.nodes.map((node) => [node.id, childrenByParent.get(node.id)?.length || 0]));
+    const visibleIds = new Set();
+    const query = normalize(options.query || "");
+    if (query) {
+        for (const node of graph.nodes) {
+            if (!searchableNodeText(node).includes(query))
+                continue;
+            visibleIds.add(node.id);
+            for (const ancestorId of getAncestorIds(node.id, parentsByChild)) {
+                visibleIds.add(ancestorId);
+            }
+        }
+    }
+    else {
+        collectExpandedTree(graph.rootId, childrenByParent, options.expandedIds, visibleIds);
+    }
+    const nodes = graph.nodes.filter((node) => visibleIds.has(node.id));
+    const edges = graph.edges.filter((edge) => visibleIds.has(edge.from) && visibleIds.has(edge.to));
+    return {
+        rootId: graph.rootId,
+        nodes,
+        edges,
+        childCounts
+    };
+}
+export function getExpandableNodeIds(graph) {
+    const hierarchyEdges = graph.edges.filter((edge) => hierarchyEdgeKinds.has(edge.kind));
+    const parentIds = new Set(hierarchyEdges.map((edge) => edge.from));
+    return graph.nodes.map((node) => node.id).filter((id) => parentIds.has(id));
+}
+export function getExpandableDescendantIds(graph, rootId) {
+    const hierarchyEdges = graph.edges.filter((edge) => hierarchyEdgeKinds.has(edge.kind));
+    const childrenByParent = groupEdges(hierarchyEdges, "from");
+    const expandableIds = new Set(getExpandableNodeIds(graph));
+    const result = [];
+    const queue = [rootId];
+    const seen = new Set();
+    for (let index = 0; index < queue.length; index += 1) {
+        const id = queue[index];
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        if (expandableIds.has(id))
+            result.push(id);
+        for (const edge of childrenByParent.get(id) || []) {
+            queue.push(edge.to);
+        }
+    }
+    return result;
+}
+export function layoutResearchGraph(graph, options) {
+    const hierarchyEdges = graph.edges.filter((edge) => hierarchyEdgeKinds.has(edge.kind));
+    const childrenByParent = groupEdges(hierarchyEdges, "from");
+    const depthById = new Map([[graph.rootId, 0]]);
+    const queue = [graph.rootId];
+    for (let index = 0; index < queue.length; index += 1) {
+        const parentId = queue[index];
+        const parentDepth = depthById.get(parentId) || 0;
+        for (const edge of childrenByParent.get(parentId) || []) {
+            if (depthById.has(edge.to))
+                continue;
+            depthById.set(edge.to, parentDepth + 1);
+            queue.push(edge.to);
+        }
+    }
+    const rows = new Map();
+    for (const node of graph.nodes) {
+        const depth = depthById.get(node.id) ?? 0;
+        rows.set(depth, [...(rows.get(depth) || []), node]);
+    }
+    const rowOffsets = new Map();
+    for (const [depth, nodes] of rows) {
+        nodes.forEach((node, offset) => rowOffsets.set(node.id, offset - (nodes.length - 1) / 2));
+        rows.set(depth, nodes);
+    }
+    const nodes = graph.nodes.map((node) => {
+        const depth = depthById.get(node.id) ?? 0;
+        const offset = rowOffsets.get(node.id) || 0;
+        const spacing = options.mode === "full" ? { depth: 610, cross: 320 } : { depth: 300, cross: 160 };
+        const position = options.direction === "LR" ? { x: depth * spacing.depth, y: offset * spacing.cross } : { x: offset * spacing.depth, y: depth * spacing.cross };
+        return { ...node, position };
+    });
+    return {
+        rootId: graph.rootId,
+        nodes,
+        edges: graph.edges,
+        childCounts: graph.childCounts
+    };
+}
+function collectExpandedTree(id, childrenByParent, expandedIds, visibleIds) {
+    visibleIds.add(id);
+    if (!expandedIds.has(id))
+        return;
+    for (const edge of childrenByParent.get(id) || []) {
+        collectExpandedTree(edge.to, childrenByParent, expandedIds, visibleIds);
+    }
+}
+function getAncestorIds(id, parentsByChild) {
+    const ancestors = [];
+    const seen = new Set();
+    const queue = [id];
+    for (let index = 0; index < queue.length; index += 1) {
+        for (const edge of parentsByChild.get(queue[index]) || []) {
+            if (seen.has(edge.from))
+                continue;
+            seen.add(edge.from);
+            ancestors.push(edge.from);
+            queue.push(edge.from);
+        }
+    }
+    return ancestors.reverse();
+}
+function groupEdges(edges, key) {
+    const grouped = new Map();
+    for (const edge of edges) {
+        grouped.set(edge[key], [...(grouped.get(edge[key]) || []), edge]);
+    }
+    return grouped;
+}
+function searchableNodeText(node) {
+    return normalize([node.title, node.id, node.type, node.file, ...(node.files || []).map((file) => file.path), node.summary, ...(node.tags || [])].filter(Boolean).join(" "));
+}
+function normalize(value) {
+    return value.trim().toLowerCase();
+}