@akira-tl/forgerelay 0.8.8 → 0.8.9

package/dist/mcp/server/core/activity-support.js

@@ -0,0 +1,70 @@
+import { runToolWithHooks } from "../../hooks/hooks.js";
+import { toolResultIsError } from "./tool-support.js";
+export function workspaceActivitySnapshot(workspace) {
+    return {
+        id: workspace.id,
+        root: workspace.root,
+        mode: workspace.mode,
+        ...(workspace.sourceRoot ? { sourceRoot: workspace.sourceRoot } : {}),
+        ...(workspace.worktree?.branch ? { branch: workspace.worktree.branch } : {}),
+        ...(workspace.worktree?.targetBranch ? { targetBranch: workspace.worktree.targetBranch } : {}),
+    };
+}
+export function activityFailureMessage(result) {
+    if (typeof result !== "object" || result === null)
+        return "Tool returned a failed result.";
+    const record = result;
+    if (Array.isArray(record.content)) {
+        const text = record.content
+            .map((entry) => {
+            if (typeof entry !== "object" || entry === null)
+                return "";
+            const value = entry.text;
+            return typeof value === "string" ? value : "";
+        })
+            .filter(Boolean)
+            .join("\n");
+        if (text)
+            return text;
+    }
+    if (typeof record.structuredContent === "object" && record.structuredContent !== null) {
+        const value = record.structuredContent.result;
+        if (typeof value === "string" && value)
+            return value;
+    }
+    return "Tool returned a failed result.";
+}
+export function standardActivityOutcome(result) {
+    return toolResultIsError(result)
+        ? { type: "failed", error: activityFailureMessage(result) }
+        : { type: "succeeded" };
+}
+export function activityRelationFor(context) {
+    return {
+        ...(context.parentActivityId ? { parentActivityId: context.parentActivityId } : {}),
+        ...(context.turnId ? { turnId: context.turnId } : {}),
+    };
+}
+export function activityRequestFor(input, context) {
+    if (!context.activityMember || !input || typeof input !== "object" || Array.isArray(input))
+        return input;
+    return {
+        ...input,
+        member: context.activityMember,
+    };
+}
+export function runActivityTool(lifecycle, workspace, conversationScopeId, tool, request, operation, outcome = standardActivityOutcome, relation = {}, auditResult) {
+    return lifecycle.run({
+        tool,
+        workspace: workspaceActivitySnapshot(workspace),
+        conversationScopeId,
+        request,
+        operation,
+        outcome,
+        ...(auditResult ? { auditResult } : {}),
+        ...relation,
+    });
+}
+export function runActivityToolWithHooks(lifecycle, hooks, workspace, conversationScopeId, request, hookOptions, relation = {}) {
+    return runActivityTool(lifecycle, workspace, conversationScopeId, hookOptions.tool, request, () => runToolWithHooks(hooks, hookOptions), standardActivityOutcome, relation);
+}

package/dist/{capabilities.js → mcp/server/core/capabilities.js}

@@ -1,6 +1,6 @@
 import { join } from "node:path";
 import { fileURLToPath } from "node:url";
-import { markAdvertisedFileSourceActivated, resolveAdvertisedFileReadPath, } from "./advertised-files.js";
+import { markAdvertisedFileSourceActivated, resolveAdvertisedFileReadPath, } from "../../filesystem/advertised-files.js";
 const CAPABILITY_GUIDE_DEFINITIONS = [
     {
         name: "lifecycle-hooks",
@@ -9,6 +9,7 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
     },
     {
         name: "managed-worktrees",
+        directory: "workspace/managed-worktrees",
         description: "Managed-worktree lifecycle, close safety, and recovery.",
         whenToRead: "Read for advanced mode=\"worktree\" flows.",
     },
@@ -41,6 +42,7 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
     },
     {
         name: "workspace-tasks",
+        directory: "workspace/workspace-tasks",
         description: "Persistent Task Lists owned by the current Workspace.",
         whenToRead: "Read before creating or maintaining Workspace Tasks.",
     },
@@ -52,14 +54,14 @@ const CAPABILITY_GUIDE_DEFINITIONS = [
     },
 ];
 function capabilityGuidesDir() {
-    return fileURLToPath(new URL("../capabilities", import.meta.url));
+    return fileURLToPath(new URL("../../../../capabilities", import.meta.url));
 }
 export function loadCapabilityGuides(config) {
     const root = capabilityGuidesDir();
     return CAPABILITY_GUIDE_DEFINITIONS
         .filter((definition) => definition.enabled?.(config) ?? true)
         .map((definition) => {
-        const baseDir = join(root, definition.name);
+        const baseDir = join(root, definition.directory ?? definition.name);
         return {
             name: definition.name,
             description: definition.description,

package/dist/{capability-registry.js → mcp/server/core/capability-registry.js}

@@ -1,6 +1,6 @@
 import { z } from "zod";
-import { MAX_CODE_INTELLIGENCE_RESULT_LIMIT, } from "./lsp/code-intelligence-types.js";
-import { batchExecuteInputSchema, } from "./operations/batch/types.js";
+import { MAX_CODE_INTELLIGENCE_RESULT_LIMIT, } from "../../../lsp/code-intelligence-types.js";
+import { batchExecuteInputSchema, } from "../../operations/batch/types.js";
 export class CapabilityError extends Error {
     code;
     constructor(code, message) {

package/dist/mcp/server/core/capability-support.js

@@ -0,0 +1,90 @@
+import { CapabilityError } from "./capability-registry.js";
+import { formatPathForPrompt } from "../../../workspaces/resources/skills.js";
+export function workspaceHookInvocation(workspace) {
+    return {
+        workspaceId: workspace.id,
+        workspaceRoot: workspace.root,
+        workspaceMode: workspace.mode,
+        sourceRoot: workspace.sourceRoot,
+    };
+}
+export function capabilityContextFor(workspace) {
+    return {
+        workspaceId: workspace.id,
+        workspaceKind: "workspace",
+        workspaceRoot: workspace.root,
+        guides: workspace.capabilityGuides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        })),
+    };
+}
+export function compositeCapabilityContext(workspaceId, guides) {
+    return {
+        workspaceId,
+        workspaceKind: "composite",
+        guides: guides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        })),
+    };
+}
+export function requireCapabilityWorkspaceRoot(context) {
+    if (!context.workspaceRoot) {
+        throw new CapabilityError("capability_unavailable", `Capability execution requires a filesystem-backed Workspace; ${context.workspaceId} is ${context.workspaceKind}.`);
+    }
+    return context.workspaceRoot;
+}
+export function runWorkspaceTasksCapability(store, workspaceId, input) {
+    switch (input.operation) {
+        case "get":
+            if (input.level === "headers")
+                return store.readHeaders(workspaceId, input.listId);
+            if (input.level === "detail")
+                return store.readTaskDetail(workspaceId, input.listId, input.taskId);
+            return store.readSummary(workspaceId);
+        case "list.create":
+            store.createList(workspaceId, { name: input.name, position: input.position });
+            return store.readSummary(workspaceId);
+        case "list.update":
+            store.updateList(workspaceId, input.listId, {
+                name: input.name,
+                state: input.state,
+                position: input.position,
+            });
+            return store.readSummary(workspaceId);
+        case "list.delete":
+            store.deleteList(workspaceId, input.listId);
+            return store.readSummary(workspaceId);
+        case "task.create":
+            store.createTask(workspaceId, input.listId, {
+                subject: input.subject,
+                content: input.content,
+                status: input.status,
+                position: input.position,
+            });
+            return store.readHeaders(workspaceId, input.listId);
+        case "task.update":
+            store.updateTask(workspaceId, input.listId, input.taskId, {
+                subject: input.subject,
+                content: input.content,
+                status: input.status,
+                position: input.position,
+            });
+            return store.readHeaders(workspaceId, input.listId);
+        case "task.delete":
+            store.deleteTask(workspaceId, input.listId, input.taskId);
+            return store.readHeaders(workspaceId, input.listId);
+    }
+}
+export async function reviewWorkspaceChanges(reviewCheckpoints, workspace) {
+    return reviewCheckpoints.reviewChanges({
+        workspaceId: workspace.id,
+        root: workspace.root,
+        markReviewed: true,
+    });
+}

package/dist/mcp/server/core/schemas.js

@@ -0,0 +1,216 @@
+import * as z from "zod/v4";
+export function resultOutputSchema(extra = {}) {
+    return {
+        result: z
+            .string()
+            .describe("Model-readable result text for follow-up reasoning and plain MCP hosts."),
+        ...extra,
+    };
+}
+export const workspaceSkillOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+});
+export const workspaceSkillDiagnosticOutputSchema = z.object({
+    type: z.enum(["warning", "error", "collision"]),
+    message: z.string(),
+    collision: z.object({
+        resourceType: z.enum(["extension", "skill", "prompt", "theme"]),
+        name: z.string(),
+    }).optional(),
+});
+export function redactSkillDiagnosticPaths(diagnostics) {
+    return diagnostics.map((diagnostic) => {
+        let message = diagnostic.message;
+        const hiddenPaths = [
+            diagnostic.path,
+            diagnostic.collision?.winnerPath,
+            diagnostic.collision?.loserPath,
+        ].filter((path) => Boolean(path));
+        for (const path of hiddenPaths) {
+            message = message.split(path).join("<skill-path>");
+        }
+        return {
+            type: diagnostic.type,
+            message,
+            ...(diagnostic.collision
+                ? {
+                    collision: {
+                        resourceType: diagnostic.collision.resourceType,
+                        name: diagnostic.collision.name,
+                    },
+                }
+                : {}),
+        };
+    });
+}
+export const capabilityFingerprintOutputSchema = z.object({
+    version: z.string(),
+    toolMode: z.enum(["minimal", "full", "codex"]),
+    capabilities: z.array(z.string()),
+});
+export const capabilityGuideOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    whenToRead: z.string(),
+    path: z.string(),
+});
+export const capabilityCatalogGuideOutputSchema = z.object({
+    name: z.string(),
+    path: z.string(),
+    readBeforeFirstUse: z.boolean(),
+});
+export const capabilityCatalogOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    available: z.boolean(),
+    unavailableReason: z.string().optional(),
+    batchPolicy: z.enum(["parallel", "serial", "unsupported"]),
+    guide: capabilityCatalogGuideOutputSchema,
+});
+export const capabilityErrorOutputSchema = z.object({
+    code: z.string(),
+    message: z.string(),
+});
+export const workspaceAgentsFileOutputSchema = z.object({
+    path: z.string(),
+    content: z.string(),
+});
+export const workspaceLocalAgentOutputSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    provider: z.string(),
+    model: z.string().optional(),
+    thinking: z.string().optional(),
+    providerAvailable: z.boolean().optional(),
+    providerUnavailableReason: z.string().optional(),
+});
+export const workspaceSubagentProviderOutputSchema = z.object({
+    name: z.string(),
+    available: z.boolean(),
+    continuationSupported: z.boolean(),
+    reason: z.string().optional(),
+});
+export const workspaceAvailableAgentsFileOutputSchema = z.object({
+    path: z.string(),
+});
+export const workspaceInventoryEntryOutputSchema = z.object({
+    label: z.string(),
+    workspaceId: z.string(),
+    root: z.string(),
+    status: z.string(),
+    state: z.enum(["active", "stale", "invalid", "closed"]),
+    mode: z.enum(["checkout", "worktree"]),
+    sourceRoot: z.string().optional(),
+    branch: z.string().optional(),
+    targetBranch: z.string().optional(),
+    managed: z.boolean(),
+    createdAt: z.string(),
+    lastUsedAt: z.string(),
+    idleMs: z.number().nonnegative(),
+    rootValid: z.boolean(),
+    current: z.boolean(),
+});
+export const workspaceInventorySummaryOutputSchema = z.object({
+    total: z.number().int().nonnegative(),
+    matching: z.number().int().nonnegative(),
+    active: z.number().int().nonnegative(),
+    stale: z.number().int().nonnegative(),
+    invalid: z.number().int().nonnegative(),
+    closed: z.number().int().nonnegative(),
+});
+export const workspaceInventoryPageOutputSchema = z.object({
+    offset: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+    hasMore: z.boolean(),
+});
+export const workspaceTaskInspectionSummaryOutputSchema = z.object({
+    level: z.literal("summary"),
+    version: z.literal(1),
+    revision: z.number().int().nonnegative(),
+    lists: z.array(z.object({
+        id: z.string(),
+        name: z.string(),
+        state: z.enum(["active", "archived"]),
+        revision: z.number().int().positive(),
+        taskCount: z.number().int().nonnegative(),
+        unfinishedTaskCount: z.number().int().nonnegative(),
+    })),
+});
+export const workspaceInspectionMemberOutputSchema = z.object({
+    name: z.string(),
+    purpose: z.string(),
+    workspaceId: z.string(),
+    known: z.boolean(),
+    location: z.enum(["local", "relay"]).optional(),
+    state: z.enum(["active", "stale", "invalid", "closed"]).optional(),
+    status: z.string().optional(),
+    routeState: z.literal("known").optional(),
+    mode: z.enum(["checkout", "worktree"]).optional(),
+    rootValid: z.boolean().optional(),
+});
+export const workspaceInspectionOutputSchema = z.union([
+    z.object({
+        workspaceId: z.string(),
+        kind: z.literal("workspace"),
+        location: z.literal("local"),
+        label: z.string(),
+        root: z.string(),
+        status: z.string(),
+        state: z.enum(["active", "stale", "invalid", "closed"]),
+        mode: z.enum(["checkout", "worktree"]),
+        sourceRoot: z.string().optional(),
+        branch: z.string().optional(),
+        targetBranch: z.string().optional(),
+        managed: z.boolean(),
+        createdAt: z.string(),
+        lastUsedAt: z.string(),
+        idleMs: z.number().nonnegative(),
+        rootValid: z.boolean(),
+        taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
+    }),
+    z.object({
+        workspaceId: z.string(),
+        kind: z.literal("workspace"),
+        location: z.literal("relay"),
+        root: z.string(),
+        routeState: z.literal("known"),
+        status: z.string().optional(),
+        state: z.enum(["active", "stale", "invalid", "closed"]).optional(),
+        mode: z.enum(["checkout", "worktree"]),
+        sourceRoot: z.string().optional(),
+        branch: z.string().optional(),
+        targetBranch: z.string().optional(),
+        managed: z.boolean().optional(),
+        createdAt: z.string().optional(),
+        lastUsedAt: z.string().optional(),
+        idleMs: z.number().nonnegative().optional(),
+        rootValid: z.boolean().optional(),
+        taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
+        relay: z.string(),
+        executionLocation: z.string(),
+    }),
+    z.object({
+        workspaceId: z.string(),
+        kind: z.literal("composite"),
+        name: z.string(),
+        status: z.enum(["active", "closed"]),
+        state: z.enum(["active", "closed"]),
+        createdAt: z.string(),
+        lastUsedAt: z.string(),
+        members: z.array(workspaceInspectionMemberOutputSchema),
+        taskSummary: workspaceTaskInspectionSummaryOutputSchema.optional(),
+    }),
+]);
+export const reviewFileOutputSchema = z.object({
+    path: z.string(),
+    previousPath: z.string().optional(),
+    type: z.enum(["change", "rename-pure", "rename-changed", "new", "deleted"]),
+    additions: z.number(),
+    removals: z.number(),
+});
+export const reviewSummaryOutputSchema = z.object({
+    files: z.number(),
+    additions: z.number(),
+    removals: z.number(),
+});

package/dist/mcp/server/core/tool-support.js

@@ -0,0 +1,207 @@
+import { resolve } from "node:path";
+import { commandPreview, logEvent, workspaceLogLabel } from "../../../runtime/logging/logger.js";
+import { formatAgentsPath } from "../../../workspaces.js";
+export function workspaceLogContext(workspace, _transportSessionId) {
+    return {
+        workspaceId: workspace.id,
+        workspace: workspaceLogLabel(workspace.root, workspace.id),
+    };
+}
+export function formatDiscoveredWorkspaceInstructions(files, workspaceRoot) {
+    return [
+        "Workspace instructions discovered for this path. Apply them to follow-up work under their directories:",
+        ...files.flatMap((file) => [
+            `--- ${formatAgentsPath(file.path, workspaceRoot)} ---`,
+            file.content.trimEnd(),
+        ]),
+    ].join("\n");
+}
+export async function assertWorkspaceInstructionsLoadedBeforeSideEffect(workspaces, workspace, paths) {
+    const discovered = new Map();
+    for (const path of paths) {
+        const absolutePath = resolve(workspace.root, path);
+        for (const file of await workspaces.discoverPathInstructions(workspace, absolutePath)) {
+            discovered.set(file.path, file);
+        }
+    }
+    if (discovered.size === 0)
+        return;
+    throw new Error([
+        formatDiscoveredWorkspaceInstructions([...discovered.values()], workspace.root),
+        "Apply these instructions, then retry this tool call. No mutation or command was executed.",
+    ].join("\n"));
+}
+export function logToolCall(config, fields) {
+    if (!config.logging.toolCalls)
+        return;
+    const { command, ...safeFields } = fields;
+    logEvent(config.logging, fields.success ? "info" : "warn", "tool_call", {
+        ...safeFields,
+        commandPreview: config.logging.shellCommands && command ? commandPreview(command) : undefined,
+    });
+}
+export function contentText(content) {
+    return content
+        .filter((item) => item.type === "text")
+        .map((item) => item.text)
+        .join("\n");
+}
+export function toolErrorPreview(content) {
+    const text = contentText(content).replace(/\s+/g, " ").trim();
+    if (!text)
+        return undefined;
+    return text.length > 240 ? `${text.slice(0, 237)}...` : text;
+}
+export function logFailedToolResponse(config, fields, content, startedAt) {
+    logToolCall(config, {
+        ...fields,
+        success: false,
+        durationMs: Math.round(performance.now() - startedAt),
+        error: toolErrorPreview(content),
+    });
+}
+export function textBlock(text) {
+    return { type: "text", text };
+}
+export function attachWorkspaceTaskReminder(result, reminder) {
+    if (!reminder || toolResultIsError(result) || typeof result !== "object" || result === null)
+        return result;
+    const content = result.content;
+    if (!Array.isArray(content))
+        return result;
+    return {
+        ...result,
+        content: [...content, textBlock(reminder)],
+    };
+}
+export function textSummary(content) {
+    const text = contentText(content);
+    return {
+        lines: text.length === 0 ? 0 : text.split("\n").length,
+        characters: text.length,
+    };
+}
+export function contentLineCount(content) {
+    if (content.length === 0)
+        return 0;
+    return content.endsWith("\n")
+        ? content.slice(0, -1).split("\n").length
+        : content.split("\n").length;
+}
+export function countDiffStats(diff) {
+    if (!diff)
+        return { additions: 0, removals: 0 };
+    let additions = 0;
+    let removals = 0;
+    for (const line of diff.split("\n")) {
+        if (line.startsWith("+") && !line.startsWith("+++"))
+            additions++;
+        if (line.startsWith("-") && !line.startsWith("---"))
+            removals++;
+    }
+    return { additions, removals };
+}
+export function newFilePatch(path, content) {
+    const lines = content.length === 0
+        ? []
+        : content.endsWith("\n")
+            ? content.slice(0, -1).split("\n")
+            : content.split("\n");
+    const hunkLength = lines.length;
+    const hunkRange = hunkLength === 0 ? "+0,0" : `+1,${hunkLength}`;
+    const body = lines.map((line) => `+${line}`).join("\n");
+    return [
+        `diff --git a/${path} b/${path}`,
+        "new file mode 100644",
+        "index 0000000..0000000",
+        "--- /dev/null",
+        `+++ b/${path}`,
+        `@@ -0,0 ${hunkRange} @@`,
+        body,
+    ]
+        .filter((line) => line.length > 0)
+        .join("\n");
+}
+export function toolResultIsError(result) {
+    return typeof result === "object" && result !== null && result.isError === true;
+}
+export function toolResultText(result) {
+    if (typeof result !== "object" || result === null)
+        return String(result ?? "");
+    const record = result;
+    if (Array.isArray(record.content)) {
+        const text = record.content
+            .map((entry) => {
+            if (typeof entry !== "object" || entry === null)
+                return "";
+            const value = entry.text;
+            return typeof value === "string" ? value : "";
+        })
+            .filter(Boolean)
+            .join("\n");
+        if (text)
+            return text;
+    }
+    if (typeof record.structuredContent === "object" && record.structuredContent !== null) {
+        const value = record.structuredContent.result;
+        if (typeof value === "string")
+            return value;
+    }
+    return "";
+}
+export function toolResultContent(result) {
+    if (typeof result !== "object" || result === null)
+        return [];
+    const content = result.content;
+    return Array.isArray(content) ? content : [];
+}
+export function remapCompositeToolResult(result, executionWorkspaceId, compositeWorkspaceId, member) {
+    if (typeof result !== "object" || result === null)
+        return result;
+    const record = result;
+    const remapped = replaceWorkspaceIdentity(record, executionWorkspaceId, compositeWorkspaceId);
+    const meta = typeof remapped._meta === "object" && remapped._meta !== null
+        ? { ...remapped._meta }
+        : undefined;
+    if (meta) {
+        const card = typeof meta.card === "object" && meta.card !== null
+            ? { ...meta.card, workspaceId: compositeWorkspaceId, member }
+            : undefined;
+        if (card)
+            meta.card = card;
+        remapped._meta = meta;
+    }
+    const structured = typeof remapped.structuredContent === "object" && remapped.structuredContent !== null
+        ? { ...remapped.structuredContent, member }
+        : undefined;
+    if (structured)
+        remapped.structuredContent = structured;
+    return remapped;
+}
+export function replaceWorkspaceIdentity(value, from, to) {
+    if (typeof value === "string")
+        return value.split(from).join(to);
+    if (Array.isArray(value))
+        return value.map((entry) => replaceWorkspaceIdentity(entry, from, to));
+    if (!value || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .map(([key, entry]) => [key, replaceWorkspaceIdentity(entry, from, to)]));
+}
+export function toolResultAgentsFiles(result) {
+    if (typeof result !== "object" || result === null)
+        return [];
+    const structured = result.structuredContent;
+    if (typeof structured !== "object" || structured === null)
+        return [];
+    const agentsFiles = structured.agentsFiles;
+    if (!Array.isArray(agentsFiles))
+        return [];
+    return agentsFiles.flatMap((entry) => {
+        if (typeof entry !== "object" || entry === null)
+            return [];
+        const path = entry.path;
+        const content = entry.content;
+        return typeof path === "string" && typeof content === "string" ? [{ path, content }] : [];
+    });
+}

package/dist/mcp/server/core/version.js

@@ -0,0 +1,9 @@
+import { readFileSync } from "node:fs";
+export const FORGERELAY_VERSION = readForgeRelayVersion();
+function readForgeRelayVersion() {
+    const packageJson = JSON.parse(readFileSync(new URL("../../../../package.json", import.meta.url), "utf8"));
+    if (typeof packageJson.version !== "string" || packageJson.version.length === 0) {
+        throw new Error("Unable to read ForgeRelay package version.");
+    }
+    return packageJson.version;
+}