@imenam/mcp-feature-analyzer 1.0.2 → 1.0.4

package/dist/shared/schemas/analysis.schema.d.ts

@@ -4,6 +4,8 @@ export declare const FILE_STATUSES: readonly ["added", "modified", "deleted", "r
 export declare const SEVERITIES: readonly ["critical", "major", "minor", "trivial"];
 export declare const FINDING_KINDS: readonly ["issue", "requirement_gap"];
 export declare const FINDING_STATUSES: readonly ["open", "ignored", "outdated"];
+export declare const EXPLANATION_SIDES: readonly ["new", "old"];
+export declare const EXPLANATION_STATUSES: readonly ["current", "outdated"];
 export declare const DIAGRAM_KINDS: readonly ["flow", "layers", "mindmap"];
 export declare const NODE_SHAPES: readonly ["box", "pill", "decision"];
 export declare const NODE_STATUSES: readonly ["new", "modified", "impacted", "existing", "finding", "missing"];
@@ -66,6 +68,41 @@ export declare const FindingSchema: z.ZodObject<{
     }>;
     createdAt: z.ZodString;
 }, z.core.$strip>;
+/**
+ * Plage de lignes décrite par une explication, bornes incluses : côté `new` (numéros
+ * du côté « nouveau », code ajouté ou conservé) ou côté `old` (numéros du côté
+ * « ancien », code supprimé).
+ */
+export declare const ExplanationLocationSchema: z.ZodObject<{
+    path: z.ZodString;
+    side: z.ZodEnum<{
+        new: "new";
+        old: "old";
+    }>;
+    startLine: z.ZodNumber;
+    endLine: z.ZodNumber;
+}, z.core.$strip>;
+/** Description, par l'agent, de ce que fait un bloc de code et de la façon dont il le fait. */
+export declare const ExplanationSchema: z.ZodObject<{
+    id: z.ZodString;
+    title: z.ZodString;
+    body: z.ZodString;
+    location: z.ZodObject<{
+        path: z.ZodString;
+        side: z.ZodEnum<{
+            new: "new";
+            old: "old";
+        }>;
+        startLine: z.ZodNumber;
+        endLine: z.ZodNumber;
+    }, z.core.$strip>;
+    anchorText: z.ZodString;
+    status: z.ZodEnum<{
+        current: "current";
+        outdated: "outdated";
+    }>;
+    createdAt: z.ZodString;
+}, z.core.$strip>;
 /** Emplacement d'une remarque : une ligne du côté « nouveau », ou le fichier entier (`line` null). */
 export declare const NoteLocationSchema: z.ZodObject<{
     path: z.ZodString;
@@ -247,6 +284,26 @@ export declare const AnalysisSchema: z.ZodObject<{
         }>;
         createdAt: z.ZodString;
     }, z.core.$strip>>;
+    explanations: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        title: z.ZodString;
+        body: z.ZodString;
+        location: z.ZodObject<{
+            path: z.ZodString;
+            side: z.ZodEnum<{
+                new: "new";
+                old: "old";
+            }>;
+            startLine: z.ZodNumber;
+            endLine: z.ZodNumber;
+        }, z.core.$strip>;
+        anchorText: z.ZodString;
+        status: z.ZodEnum<{
+            current: "current";
+            outdated: "outdated";
+        }>;
+        createdAt: z.ZodString;
+    }, z.core.$strip>>;
     notes: z.ZodArray<z.ZodObject<{
         id: z.ZodString;
         location: z.ZodNullable<z.ZodObject<{
@@ -323,6 +380,8 @@ export type FileStatus = (typeof FILE_STATUSES)[number];
 export type Severity = (typeof SEVERITIES)[number];
 export type FindingKind = (typeof FINDING_KINDS)[number];
 export type FindingStatus = (typeof FINDING_STATUSES)[number];
+export type ExplanationSide = (typeof EXPLANATION_SIDES)[number];
+export type ExplanationStatus = (typeof EXPLANATION_STATUSES)[number];
 export type DiagramKind = (typeof DIAGRAM_KINDS)[number];
 export type NodeShape = (typeof NODE_SHAPES)[number];
 export type NodeStatus = (typeof NODE_STATUSES)[number];
@@ -332,6 +391,8 @@ export type Editor = (typeof EDITORS)[number];
 export type FileEntry = z.infer<typeof FileEntrySchema>;
 export type FindingLocation = z.infer<typeof FindingLocationSchema>;
 export type Finding = z.infer<typeof FindingSchema>;
+export type ExplanationLocation = z.infer<typeof ExplanationLocationSchema>;
+export type Explanation = z.infer<typeof ExplanationSchema>;
 export type NoteLocation = z.infer<typeof NoteLocationSchema>;
 export type Note = z.infer<typeof NoteSchema>;
 export type DiagramNodeLocation = z.infer<typeof DiagramNodeLocationSchema>;

package/dist/shared/schemas/analysis.schema.js

@@ -4,6 +4,8 @@ export const FILE_STATUSES = ["added", "modified", "deleted", "renamed"];
 export const SEVERITIES = ["critical", "major", "minor", "trivial"];
 export const FINDING_KINDS = ["issue", "requirement_gap"];
 export const FINDING_STATUSES = ["open", "ignored", "outdated"];
+export const EXPLANATION_SIDES = ["new", "old"];
+export const EXPLANATION_STATUSES = ["current", "outdated"];
 export const DIAGRAM_KINDS = ["flow", "layers", "mindmap"];
 export const NODE_SHAPES = ["box", "pill", "decision"];
 export const NODE_STATUSES = ["new", "modified", "impacted", "existing", "finding", "missing"];
@@ -55,6 +57,29 @@ export const FindingSchema = z.object({
     status: z.enum(FINDING_STATUSES),
     createdAt: IsoDateSchema,
 });
+/**
+ * Plage de lignes décrite par une explication, bornes incluses : côté `new` (numéros
+ * du côté « nouveau », code ajouté ou conservé) ou côté `old` (numéros du côté
+ * « ancien », code supprimé).
+ */
+export const ExplanationLocationSchema = z.object({
+    path: z.string().min(1),
+    side: z.enum(EXPLANATION_SIDES),
+    startLine: LineSchema,
+    endLine: LineSchema,
+});
+/** Description, par l'agent, de ce que fait un bloc de code et de la façon dont il le fait. */
+export const ExplanationSchema = z.object({
+    id: ItemIdSchema,
+    title: z.string().min(1),
+    body: z.string().min(1),
+    location: ExplanationLocationSchema,
+    /** Texte exact des lignes décrites au moment où l'explication a été ancrée. */
+    anchorText: z.string(),
+    /** `outdated` quand les lignes décrites ont changé depuis, au recalcul du snapshot. */
+    status: z.enum(EXPLANATION_STATUSES),
+    createdAt: IsoDateSchema,
+});
 /** Emplacement d'une remarque : une ligne du côté « nouveau », ou le fichier entier (`line` null). */
 export const NoteLocationSchema = z.object({
     path: z.string().min(1),
@@ -140,6 +165,7 @@ export const AnalysisSchema = z.object({
     summary: z.array(z.string().min(1)),
     files: z.array(FileEntrySchema),
     findings: z.array(FindingSchema),
+    explanations: z.array(ExplanationSchema),
     notes: z.array(NoteSchema),
     diagrams: z.array(DiagramSchema),
     review: ReviewSchema,

package/dist/shared/schemas/api.schema.d.ts

@@ -19,6 +19,10 @@ export declare const AddNoteBodySchema: z.ZodObject<{
     text: z.ZodString;
     baseRevision: z.ZodNumber;
 }, z.core.$strict>;
+export declare const UpdateNoteBodySchema: z.ZodObject<{
+    text: z.ZodString;
+    baseRevision: z.ZodNumber;
+}, z.core.$strict>;
 export declare const DeleteNoteBodySchema: z.ZodObject<{
     baseRevision: z.ZodNumber;
 }, z.core.$strict>;
@@ -35,6 +39,7 @@ export declare const SubmitReviewBodySchema: z.ZodObject<{
 export type SetFileReviewedBody = z.infer<typeof SetFileReviewedBodySchema>;
 export type SetFindingStatusBody = z.infer<typeof SetFindingStatusBodySchema>;
 export type AddNoteBody = z.infer<typeof AddNoteBodySchema>;
+export type UpdateNoteBody = z.infer<typeof UpdateNoteBodySchema>;
 export type DeleteNoteBody = z.infer<typeof DeleteNoteBodySchema>;
 export type SubmitReviewBody = z.infer<typeof SubmitReviewBodySchema>;
 /** Données IPC des requêtes de la GUI qui visent une analyse. */
@@ -70,6 +75,14 @@ export declare const AddNoteRequestSchema: z.ZodObject<{
         baseRevision: z.ZodNumber;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export declare const UpdateNoteRequestSchema: z.ZodObject<{
+    analysisId: z.ZodString;
+    noteId: z.ZodString;
+    body: z.ZodObject<{
+        text: z.ZodString;
+        baseRevision: z.ZodNumber;
+    }, z.core.$strict>;
+}, z.core.$strict>;
 export declare const DeleteNoteRequestSchema: z.ZodObject<{
     analysisId: z.ZodString;
     noteId: z.ZodString;

package/dist/shared/schemas/api.schema.js

@@ -22,6 +22,10 @@ export const AddNoteBodySchema = z.strictObject({
     text: z.string().trim().min(1, "the note text is empty"),
     baseRevision: BaseRevisionSchema,
 });
+export const UpdateNoteBodySchema = z.strictObject({
+    text: z.string().trim().min(1, "the note text is empty"),
+    baseRevision: BaseRevisionSchema,
+});
 export const DeleteNoteBodySchema = z.strictObject({
     baseRevision: BaseRevisionSchema,
 });
@@ -39,6 +43,10 @@ export const SetFindingStatusRequestSchema = AnalysisRequestSchema.extend({
     body: SetFindingStatusBodySchema,
 });
 export const AddNoteRequestSchema = AnalysisRequestSchema.extend({ body: AddNoteBodySchema });
+export const UpdateNoteRequestSchema = AnalysisRequestSchema.extend({
+    noteId: z.string().min(1),
+    body: UpdateNoteBodySchema,
+});
 export const DeleteNoteRequestSchema = AnalysisRequestSchema.extend({
     noteId: z.string().min(1),
     body: DeleteNoteBodySchema,

package/dist/shared/schemas/ipc.schema.d.ts

@@ -25,5 +25,5 @@ export type IPCMessage = z.infer<typeof IPCMessageSchema>;
 export declare const PUSHED_EVENT_TYPES: readonly ["INITIAL_STATE", "ANALYSES_UPDATED", "ANALYSIS_UPDATED"];
 export type PushedEventType = (typeof PUSHED_EVENT_TYPES)[number];
 /** Requêtes du GUI worker au maître ; chacune reçoit une réponse de même `correlationId`. */
-export declare const GUI_REQUEST_TYPES: readonly ["GET_CONFIG", "LIST_ANALYSES", "GET_ANALYSIS", "GET_DIFF", "SET_FILE_REVIEWED", "SET_FINDING_STATUS", "ADD_NOTE", "DELETE_NOTE", "SUBMIT_REVIEW"];
+export declare const GUI_REQUEST_TYPES: readonly ["GET_CONFIG", "LIST_ANALYSES", "GET_ANALYSIS", "GET_DIFF", "SET_FILE_REVIEWED", "SET_FINDING_STATUS", "ADD_NOTE", "UPDATE_NOTE", "DELETE_NOTE", "SUBMIT_REVIEW"];
 export type GuiRequestType = (typeof GUI_REQUEST_TYPES)[number];

package/dist/shared/schemas/ipc.schema.js

@@ -25,6 +25,7 @@ export const GUI_REQUEST_TYPES = [
     "SET_FILE_REVIEWED",
     "SET_FINDING_STATUS",
     "ADD_NOTE",
+    "UPDATE_NOTE",
     "DELETE_NOTE",
     "SUBMIT_REVIEW",
 ];

package/dist/src/core/agent-repo.d.ts

@@ -0,0 +1,4 @@
+import { type RepoAccess } from "./git.js";
+import { type Run } from "./gateway-exec.js";
+/** Accès au dépôt `repoPath` de la machine de l'agent, par les commandes que `run` y fait exécuter. */
+export declare function agentRepo(repoPath: string, run: Run): RepoAccess;

package/dist/src/core/agent-repo.js

@@ -0,0 +1,172 @@
+/**
+ * Accès au dépôt placé sur la machine de l'agent, quand ce serveur tourne derrière
+ * mcp-http-gateway : chaque commande est exécutée par le relais agent (voir
+ * gateway-exec.ts), dans `repoPath`, et sa sortie revient dans le rappel de l'outil.
+ *
+ * - git lit le dépôt ; `node` lit les fichiers de la copie de travail.
+ * - La sortie d'une commande est limitée à 1 Mio par le relais : le diff est demandé
+ *   fichier par fichier, et un contenu tronqué est rendu `null`.
+ * - Les commandes d'une même demande sont groupées par paquets de STEPS_PER_ROUND, pour
+ *   borner la taille de chaque rappel.
+ */
+import path from "path";
+import { toPosixPath } from "./diff-parser.js";
+import { GitError } from "./errors.js";
+import { DIFF_ARGS, assertRefShape } from "./git.js";
+import { RELAY_MAX_OUTPUT_BYTES, isTruncated } from "./gateway-exec.js";
+/** Nombre maximal de commandes par demande d'exécution. */
+const STEPS_PER_ROUND = 25;
+/** Variable d'environnement qui porte le chemin du fichier à lire. */
+const FILE_ENV = "FEATURE_ANALYZER_FILE";
+/** Écrit sur stdout le contenu du fichier FILE_ENV, ou la cible POSIX d'un lien symbolique. */
+const READ_FILE_SCRIPT = [
+    'const fs = require("fs");',
+    `const file = process.env.${FILE_ENV};`,
+    "process.stdout.write(fs.lstatSync(file).isSymbolicLink()",
+    '  ? fs.readlinkSync(file).split(String.fromCharCode(92)).join("/")',
+    "  : fs.readFileSync(file));",
+].join("\n");
+const MIB = `${RELAY_MAX_OUTPUT_BYTES / (1024 * 1024)} MiB`;
+function detail(result) {
+    return (result.error ?? (result.stderr.trim() || result.stdout.trim())) || "no output";
+}
+/** Accès au dépôt `repoPath` de la machine de l'agent, par les commandes que `run` y fait exécuter. */
+export function agentRepo(repoPath, run) {
+    function gitStep(args) {
+        return {
+            command: "git",
+            args: ["-c", "core.quotepath=false", ...args],
+            cwd: repoPath,
+            env: { GIT_LITERAL_PATHSPECS: "1", GIT_TERMINAL_PROMPT: "0" },
+        };
+    }
+    function readFileStep(filePath) {
+        return {
+            command: "node",
+            args: ["--input-type=commonjs", "-e", READ_FILE_SCRIPT],
+            cwd: repoPath,
+            env: { [FILE_ENV]: filePath },
+        };
+    }
+    /** Échec de lancement d'une commande : dossier absent ou exécutable introuvable. */
+    function launchError(step, result) {
+        return new GitError(`Could not run ${step.command} in "${repoPath}" on the agent's machine (${result.error}). ` +
+            `Check that repo_path exists on that machine and that ${step.command} is on its PATH.`);
+    }
+    /** Exécute une seule commande et rend son résultat ; un échec de lancement lève une erreur. */
+    async function runOne(step) {
+        const [result] = await run([step]);
+        if (!result)
+            throw new GitError(`The agent relay returned no result for ${step.command} ${step.args.join(" ")}.`);
+        if (result.error !== undefined)
+            throw launchError(step, result);
+        return result;
+    }
+    /** Exécute une commande git qui doit réussir, avec une sortie complète. */
+    async function runGit(args) {
+        const result = await runOne(gitStep(args));
+        if (result.code !== 0)
+            throw new GitError(`git ${args.join(" ")} failed in ${repoPath} on the agent's machine: ${detail(result)}`);
+        if (isTruncated(result.stdout)) {
+            throw new GitError(`The output of git ${args.join(" ")} exceeds ${MIB}, the output limit of the agent relay.`);
+        }
+        return result.stdout;
+    }
+    /**
+     * Exécute une commande par élément, par paquets. Le relais s'arrête à la première
+     * commande en échec : `onFailure` rend l'erreur à lever pour cet élément.
+     */
+    async function runEach(items, toStep, onFailure) {
+        const all = [];
+        for (let start = 0; start < items.length; start += STEPS_PER_ROUND) {
+            const chunk = items.slice(start, start + STEPS_PER_ROUND);
+            const steps = chunk.map(toStep);
+            const results = await run(steps);
+            chunk.forEach((item, index) => {
+                const result = results[index];
+                if (!result)
+                    throw new GitError(`The agent relay returned no result for ${steps[index].command} ${steps[index].args.join(" ")}.`);
+                if (result.error !== undefined)
+                    throw launchError(steps[index], result);
+                if (result.code !== 0)
+                    throw onFailure(item, result);
+                all.push(result);
+            });
+        }
+        return all;
+    }
+    /** Contenu rendu par le relais, ou null s'il a été tronqué. */
+    function contentOf(result) {
+        return isTruncated(result.stdout) ? null : Buffer.from(result.stdout, "utf-8");
+    }
+    return {
+        async assertRepoRoot() {
+            if (!path.posix.isAbsolute(repoPath) && !path.win32.isAbsolute(repoPath)) {
+                throw new GitError(`repo_path must be an absolute path on the agent's machine, got "${repoPath}".`);
+            }
+            const args = ["rev-parse", "--show-toplevel", "--show-cdup"];
+            const result = await runOne(gitStep(args));
+            if (result.code !== 0) {
+                if (/not a git repository/i.test(result.stderr)) {
+                    throw new GitError(`repo_path "${repoPath}" is not inside a git repository.`);
+                }
+                throw new GitError(`git ${args.join(" ")} failed in ${repoPath} on the agent's machine: ${detail(result)}`);
+            }
+            const [topLevel, cdup] = result.stdout.split("\n");
+            if (cdup.trim() !== "") {
+                throw new GitError(`repo_path "${repoPath}" is not the root of its git repository. Use the repository root: ${topLevel.trim()}`);
+            }
+        },
+        async resolveCommit(ref, role) {
+            assertRefShape(ref, role);
+            const result = await runOne(gitStep(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]));
+            if (result.code !== 0) {
+                throw new GitError(`Unknown ${role} ref "${ref}" in ${repoPath}. Use a branch name, a tag or a commit sha that exists in this repository.`);
+            }
+            return result.stdout.trim();
+        },
+        async diff(range) {
+            const listing = await runGit([
+                "diff",
+                "--no-color",
+                "--no-ext-diff",
+                "--no-relative",
+                "--find-renames",
+                "--name-status",
+                "-z",
+                ...range,
+                "--",
+            ]);
+            const tokens = listing.split("\0");
+            const files = [];
+            for (let index = 0; index < tokens.length && tokens[index] !== "";) {
+                const pathCount = /^[RC]/.test(tokens[index]) ? 2 : 1;
+                files.push(tokens.slice(index + 1, index + 1 + pathCount));
+                index += 1 + pathCount;
+            }
+            const results = await runEach(files, (paths) => gitStep([...DIFF_ARGS, ...range, "--", ...paths]), (paths, result) => new GitError(`git diff of "${paths.join('" -> "')}" failed on the agent's machine: ${detail(result)}`));
+            return results
+                .map((result, index) => {
+                if (isTruncated(result.stdout)) {
+                    throw new GitError(`The diff of "${files[index].at(-1)}" exceeds ${MIB}, the output limit of the agent relay: this change cannot be analysed through the gateway.`);
+                }
+                return result.stdout;
+            })
+                .join("");
+        },
+        async readCommitFiles(commit, paths) {
+            const results = await runEach(paths, (filePath) => gitStep(["cat-file", "blob", `${commit}:${filePath}`]), (filePath) => new GitError(`"${filePath}" is in the diff but is not a file of commit ${commit} (submodule or unreadable entry).`));
+            return new Map(paths.map((filePath, index) => [filePath, contentOf(results[index])]));
+        },
+        async untrackedFiles() {
+            return (await runGit(["ls-files", "--others", "--exclude-standard", "-z"]))
+                .split("\0")
+                .filter((entry) => entry !== "")
+                .map(toPosixPath);
+        },
+        async readWorkingFiles(paths) {
+            const results = await runEach(paths, readFileStep, (filePath, result) => new GitError(`Could not read "${filePath}" in ${repoPath} on the agent's machine: ${detail(result)}`));
+            return new Map(paths.map((filePath, index) => [filePath, contentOf(results[index])]));
+        },
+    };
+}

package/dist/src/core/analysis-store.js

@@ -269,6 +269,7 @@ export class AnalysisStore {
             summary: input.summary ?? [],
             files: snapshot.files.map((file) => ({ ...file, reviewed: false })),
             findings: [],
+            explanations: [],
             notes: [],
             diagrams: [],
             review: pendingReview(),

package/dist/src/core/gateway-exec.d.ts

@@ -0,0 +1,27 @@
+import type { ToolResult } from "../tools/types.js";
+export declare const EXEC_ARG = "_gateway_exec";
+export declare const EXEC_META = "gateway/exec";
+export declare const EXEC_VERSION = 1;
+/** Taille maximale de la sortie d'une étape conservée par le relais agent. */
+export declare const RELAY_MAX_OUTPUT_BYTES: number;
+export interface ExecStep {
+    command: string;
+    args: string[];
+    cwd?: string;
+    env?: Record<string, string>;
+}
+export interface StepResult {
+    code: number | null;
+    stdout: string;
+    stderr: string;
+    error?: string;
+}
+export type Run = (steps: ExecStep[]) => Promise<StepResult[]>;
+/** Vrai si le relais agent a tronqué cette sortie. */
+export declare function isTruncated(output: string): boolean;
+/**
+ * Point d'entrée d'un outil qui s'exécute sur la machine de l'agent. Au premier appel,
+ * démarre `tool` ; aux rappels du relais agent, reprend la fonction là où elle attend.
+ * `exec` est la valeur de l'argument `_gateway_exec` de l'appel.
+ */
+export declare function handleAgentExec(exec: unknown, tool: (run: Run) => Promise<ToolResult>): Promise<ToolResult>;

package/dist/src/core/gateway-exec.js

@@ -0,0 +1,115 @@
+/**
+ * Exécution de commandes sur la machine de l'agent, par le relais agent de
+ * mcp-http-gateway (`mcp-http-gateway --mcp`).
+ *
+ * Convention, entre le relais agent et un MCP placé derrière le gateway :
+ *
+ * - Quand la route de ce MCP figure dans sa liste blanche (GATEWAY_EXEC_ROUTES), le
+ *   relais agent ajoute à chaque appel d'outil l'argument réservé `_gateway_exec` :
+ *   `{ version, cwd, gatewayToken }`. `cwd` est son dossier de lancement.
+ * - Le MCP peut répondre par une demande d'exécution au lieu d'un résultat final :
+ *   `_meta["gateway/exec"] = { id, steps }`. Chaque étape est `{ command, args, cwd, env }`,
+ *   lancée sans shell ; `cwd` est résolu par rapport au dossier de lancement du relais.
+ * - Le relais agent exécute les étapes dans l'ordre et s'arrête à la première qui
+ *   échoue. Il rappelle alors le même outil avec
+ *   `_gateway_exec.continuation = { id, results }`, un résultat par étape exécutée.
+ *   La sortie standard de chaque étape est tronquée au-delà de 1 Mio.
+ *
+ * Un outil s'écrit comme une fonction asynchrone qui appelle `run(steps)` : chaque
+ * appel suspend la fonction jusqu'au rappel du relais agent qui porte les résultats.
+ */
+import { randomUUID } from "crypto";
+export const EXEC_ARG = "_gateway_exec";
+export const EXEC_META = "gateway/exec";
+export const EXEC_VERSION = 1;
+/** Taille maximale de la sortie d'une étape conservée par le relais agent. */
+export const RELAY_MAX_OUTPUT_BYTES = 1024 * 1024;
+/** Mention ajoutée par le relais agent à la fin d'une sortie tronquée. */
+const TRUNCATION_MARK = /\n\[sortie tronquée à \d+ octets\]$/;
+/** Délai laissé au relais agent pour rendre les résultats d'une demande. */
+const CONTINUATION_TTL_MS = 30 * 60 * 1000;
+/** Vrai si le relais agent a tronqué cette sortie. */
+export function isTruncated(output) {
+    return TRUNCATION_MARK.test(output);
+}
+const flows = new Map();
+function nextEvent(flow) {
+    return new Promise((resolve) => {
+        flow.emit = resolve;
+    });
+}
+function toToolResult(flow, event) {
+    if (event.kind === "done") {
+        flows.delete(flow.id);
+        return event.result;
+    }
+    if (event.kind === "failed") {
+        flows.delete(flow.id);
+        throw event.error;
+    }
+    flow.steps = event.steps;
+    flow.timer = setTimeout(() => {
+        flows.delete(flow.id);
+        flow.abort?.(new Error("Timed out waiting for the agent relay to return the command results."));
+    }, CONTINUATION_TTL_MS);
+    flow.timer.unref();
+    return {
+        content: [{ type: "text", text: "Command execution request for the agent's machine, to be handled by the agent relay." }],
+        _meta: { [EXEC_META]: { id: flow.id, steps: event.steps } },
+    };
+}
+function assertAnnounced(raw) {
+    if (!raw || typeof raw !== "object") {
+        const route = process.env.MCP_SERVER_ROUTE?.trim() || "the route of this MCP";
+        throw new Error("This tool runs git on the agent's machine, through the agent relay (mcp-http-gateway --mcp), " +
+            `and the relay did not offer command execution: add ${route} to GATEWAY_EXEC_ROUTES in the "env" block ` +
+            "of the relay configuration, with a version of mcp-http-gateway that supports it.");
+    }
+    if (raw.version !== EXEC_VERSION) {
+        throw new Error(`Unsupported agent relay execution version: ${raw.version} (expected ${EXEC_VERSION}).`);
+    }
+}
+function parseResults(raw, steps) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > steps.length) {
+        throw new Error("Invalid command results from the agent relay: one result is expected per step run.");
+    }
+    return raw.map((r) => ({
+        code: typeof r?.code === "number" ? r.code : null,
+        stdout: typeof r?.stdout === "string" ? r.stdout : "",
+        stderr: typeof r?.stderr === "string" ? r.stderr : "",
+        ...(typeof r?.error === "string" ? { error: r.error } : {}),
+    }));
+}
+/**
+ * Point d'entrée d'un outil qui s'exécute sur la machine de l'agent. Au premier appel,
+ * démarre `tool` ; aux rappels du relais agent, reprend la fonction là où elle attend.
+ * `exec` est la valeur de l'argument `_gateway_exec` de l'appel.
+ */
+export async function handleAgentExec(exec, tool) {
+    assertAnnounced(exec);
+    const continuation = exec.continuation;
+    if (continuation) {
+        const flow = flows.get(continuation.id);
+        if (!flow || !flow.resume || !flow.steps) {
+            throw new Error("Unknown or expired execution continuation (the MCP server may have restarted): call the tool again.");
+        }
+        const results = parseResults(continuation.results, flow.steps);
+        clearTimeout(flow.timer);
+        const resume = flow.resume;
+        flow.resume = undefined;
+        flow.abort = undefined;
+        const event = nextEvent(flow);
+        resume(results);
+        return toToolResult(flow, await event);
+    }
+    const flow = { id: randomUUID(), emit: () => { } };
+    flows.set(flow.id, flow);
+    const event = nextEvent(flow);
+    const run = (steps) => new Promise((resolve, reject) => {
+        flow.resume = resolve;
+        flow.abort = reject;
+        flow.emit({ kind: "exec", steps });
+    });
+    tool(run).then((result) => flow.emit({ kind: "done", result }), (error) => flow.emit({ kind: "failed", error }));
+    return toToolResult(flow, await event);
+}

package/dist/src/core/git.d.ts

@@ -26,10 +26,35 @@ export interface ComputedSnapshot {
     diff: FileDiff[];
 }
 /**
- * Calcule le snapshot d'une analyse avec git.
+ * Accès au dépôt sur la machine qui le porte : git et copie de travail.
+ * Un contenu `null` dépasse ce que l'accès sait transférer.
+ */
+export interface RepoAccess {
+    /** Vérifie que le chemin du dépôt désigne la racine d'un dépôt git. */
+    assertRepoRoot(): Promise<void>;
+    /** Résout une ref en sha de commit ; erreur explicite si elle est inconnue. */
+    resolveCommit(ref: string, role: string): Promise<string>;
+    /** Sortie de `git diff` (DIFF_ARGS) pour `range`, par ex. `["<base>...<head>"]` ou `["HEAD"]`. */
+    diff(range: string[]): Promise<string>;
+    /** Contenu des fichiers `paths` dans le commit `commit`. */
+    readCommitFiles(commit: string, paths: string[]): Promise<Map<string, Buffer | null>>;
+    /** Fichiers non suivis et non ignorés, chemins POSIX relatifs au dépôt. */
+    untrackedFiles(): Promise<string[]>;
+    /** Contenu des fichiers `paths` de la copie de travail ; un lien symbolique donne sa cible. */
+    readWorkingFiles(paths: string[]): Promise<Map<string, Buffer | null>>;
+}
+export declare const DIFF_ARGS: string[];
+/** Vrai si le contenu contient un octet nul dans ses 8000 premiers octets (même règle que git). */
+export declare function looksBinary(content: Buffer): boolean;
+/** Accès direct au dépôt, sur la machine de ce serveur. */
+export declare function localRepo(repoPath: string): RepoAccess;
+/** Vérifie une ref fournie par l'agent avant de la passer à git. */
+export declare function assertRefShape(ref: string, role: string): void;
+/**
+ * Calcule le snapshot d'une analyse avec git, par `repo` (accès local par défaut).
  * - `branch` : diff `base...head` (head vaut `HEAD` par défaut), contenu lu dans le commit de tête ;
  * - `working_tree` : diff de HEAD vers la copie de travail, index compris, fichiers non suivis
  *   présentés comme ajoutés, contenu lu sur disque.
  * Les fichiers sont triés par chemin ; `reviewed` vaut false partout.
  */
-export declare function computeSnapshot(request: SnapshotRequest): Promise<ComputedSnapshot>;
+export declare function computeSnapshot(request: SnapshotRequest, repo?: RepoAccess): Promise<ComputedSnapshot>;