@akira-tl/forgerelay 0.1.1 → 0.2.1

package/dist/logger.js

@@ -1,3 +1,5 @@
+import { basename } from "node:path";
+import { styleText } from "node:util";
 const LEVEL_WEIGHT = {
     silent: 0,
     error: 1,
@@ -5,6 +7,12 @@ const LEVEL_WEIGHT = {
     info: 3,
     debug: 4,
 };
+const LEVEL_STYLE = {
+    error: "red",
+    warn: "yellow",
+    info: "green",
+    debug: "gray",
+};
 export function shouldLog(config, level) {
     return LEVEL_WEIGHT[config.level] >= LEVEL_WEIGHT[level];
 }
@@ -17,7 +25,10 @@ export function logEvent(config, level, event, fields = {}) {
         event,
         ...fields,
     };
-    const line = config.format === "pretty" ? formatPretty(entry) : JSON.stringify(entry);
+    const stream = level === "error" || level === "warn" ? process.stderr : process.stdout;
+    const line = config.format === "pretty"
+        ? formatPrettyLogEntry(entry, { colorize: true, stream })
+        : JSON.stringify(entry);
     if (level === "error") {
         console.error(line);
     }
@@ -45,25 +56,156 @@ export function requestPath(req) {
 export function sessionIdPrefix(sessionId) {
     return sessionId ? sessionId.slice(0, 8) : undefined;
 }
+export function workspaceLogLabel(root, workspaceId) {
+    const shortWorkspaceId = workspaceId.startsWith("ws_")
+        ? `ws_${workspaceId.slice(3, 11)}`
+        : workspaceId.slice(0, 8);
+    return `${basename(root)}/${shortWorkspaceId}`;
+}
 export function commandPreview(command) {
     const normalized = command.replace(/\s+/g, " ").trim();
     return normalized.length > 120 ? `${normalized.slice(0, 117)}...` : normalized;
 }
+export function formatPrettyLogEntry(entry, options = {}) {
+    const level = logLevel(entry.level);
+    const time = formatTimestamp(entry.ts);
+    const source = stringField(entry.workspace) ?? stringField(entry.workspaceId) ?? "forgerelay";
+    const session = stringField(entry.session) ?? stringField(entry.sessionIdPrefix);
+    const prefix = [
+        style("gray", time, options),
+        `[${style(LEVEL_STYLE[level], level.toUpperCase(), options)}]`,
+        style(["cyan", "underline"], source, options),
+        session ? style("gray", `session:${session}`, options) : undefined,
+        style("gray", "|", options),
+    ].filter((value) => Boolean(value)).join(" ");
+    return `${prefix} ${formatPrettyMessage(entry, options)}`;
+}
 function firstHeaderValue(value) {
     return value?.split(",")[0]?.trim() || undefined;
 }
-function formatPretty(entry) {
-    const ts = String(entry.ts);
-    const level = String(entry.level).toUpperCase();
-    const event = String(entry.event);
-    const rest = Object.entries(entry)
-        .filter(([key, value]) => !["ts", "level", "event"].includes(key) && value !== undefined)
-        .map(([key, value]) => `${key}=${formatPrettyValue(value)}`)
-        .join(" ");
-    return rest ? `${ts} ${level} ${event} ${rest}` : `${ts} ${level} ${event}`;
-}
-function formatPrettyValue(value) {
-    if (typeof value === "string")
-        return JSON.stringify(value);
-    return JSON.stringify(value);
+function formatPrettyMessage(entry, options) {
+    switch (String(entry.event)) {
+        case "tool_call":
+        case "artifact_tool_call":
+            return formatToolMessage(entry, options);
+        case "hook_call":
+            return formatHookMessage(entry, options);
+        case "http_request":
+            return formatHttpMessage(entry, options);
+        case "mcp_session_created":
+            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} created`;
+        case "mcp_session_closed":
+            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} closed`;
+        case "mcp_session_close_failed":
+            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} close -> ${style("red", "error", options)}`;
+        case "auth_denied":
+            return `auth denied${entry.reason ? `: ${String(entry.reason)}` : ""}`;
+        case "mcp_request_error":
+            return `mcp request -> ${style("red", `error${entry.error ? `: ${String(entry.error)}` : ""}`, options)}`;
+        default:
+            return formatGenericMessage(entry);
+    }
+}
+function formatToolMessage(entry, options) {
+    const tool = stringField(entry.tool) ?? String(entry.event ?? "tool");
+    const target = toolTarget(entry, tool);
+    const operation = target ? `${tool} ${target}` : tool;
+    const result = toolResult(entry, tool, options);
+    return `${operation} -> ${result}`;
+}
+function toolTarget(entry, tool) {
+    if (isShellTool(tool)) {
+        return stringField(entry.commandPreview) ?? stringField(entry.workingDirectory);
+    }
+    return stringField(entry.path) ?? stringField(entry.workingDirectory);
+}
+function toolResult(entry, tool, options) {
+    if (entry.running === true) {
+        const processSessionId = entry.processSessionId;
+        return style("yellow", processSessionId === undefined ? "running" : `running process:${String(processSessionId)}`, options);
+    }
+    const exitCode = numberField(entry.exitCode) ?? exitCodeFromError(entry.error);
+    if (isShellTool(tool)) {
+        if (exitCode !== undefined) {
+            return style(exitCode === 0 ? "green" : "red", `exit=${exitCode}`, options);
+        }
+        if (entry.success === true)
+            return style("green", "exit=0", options);
+    }
+    if (entry.success === false) {
+        const error = stringField(entry.error);
+        return style("red", error ? `error: ${error}` : "error", options);
+    }
+    if (entry.success === true)
+        return style("green", "ok", options);
+    return "done";
+}
+function formatHookMessage(entry, options) {
+    const name = stringField(entry.hookName) ?? "hook";
+    const event = stringField(entry.hookEvent);
+    const operation = event ? `hook ${name} ${event}` : `hook ${name}`;
+    const exitCode = exitCodeFromHookError(entry.error);
+    if (entry.success === false) {
+        if (exitCode !== undefined)
+            return `${operation} -> ${style("red", `exit=${exitCode}`, options)}`;
+        const error = stringField(entry.error);
+        return `${operation} -> ${style("red", error ? `error: ${error}` : "error", options)}`;
+    }
+    return `${operation} -> ${style("green", "exit=0", options)}`;
+}
+function formatHttpMessage(entry, options) {
+    const method = stringField(entry.method) ?? "HTTP";
+    const path = stringField(entry.path) ?? "/";
+    const status = numberField(entry.status);
+    const statusText = status === undefined ? "done" : String(status);
+    const statusStyle = status !== undefined && status >= 400 ? "red" : "green";
+    return `http ${method} ${path} -> ${style(statusStyle, statusText, options)}`;
+}
+function formatGenericMessage(entry) {
+    const event = String(entry.event ?? "log");
+    const detail = [entry.reason, entry.error]
+        .map((value) => stringField(value))
+        .find((value) => value !== undefined);
+    return detail ? `${event}: ${detail}` : event;
+}
+function formatTimestamp(value) {
+    const date = new Date(String(value));
+    if (Number.isNaN(date.getTime()))
+        return String(value ?? "");
+    const two = (part) => String(part).padStart(2, "0");
+    return `${two(date.getMonth() + 1)}-${two(date.getDate())} ${two(date.getHours())}:${two(date.getMinutes())}:${two(date.getSeconds())}`;
+}
+function logLevel(value) {
+    return value === "error" || value === "warn" || value === "debug" ? value : "info";
+}
+function stringField(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function numberField(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
+function exitCodeFromError(value) {
+    const error = stringField(value);
+    if (!error)
+        return undefined;
+    const match = error.match(/Command exited with code (-?\d+)/i);
+    return match ? Number(match[1]) : undefined;
+}
+function exitCodeFromHookError(value) {
+    const error = stringField(value);
+    if (!error)
+        return undefined;
+    const match = error.match(/exited with code (-?\d+)/i);
+    return match ? Number(match[1]) : undefined;
+}
+function isShellTool(tool) {
+    return tool === "bash" || tool === "exec_command" || tool === "write_stdin";
+}
+function style(format, text, options) {
+    if (options.colorize !== true)
+        return text;
+    return styleText(format, text, {
+        validateStream: options.validateStream ?? true,
+        stream: options.stream ?? process.stdout,
+    });
 }

package/dist/mcp/server-instructions.js

@@ -20,10 +20,10 @@ export function buildToolDescriptions(config) {
         ? ` In minimal tool mode, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} are disabled, so shell commands may be used for equivalent search and directory inspection.`
         : "";
     return {
-        read: `Read a file inside an open workspace. Instruction files returned by ${toolNames.openWorkspace} and advertised skill files are also readable when applicable.${skillCapability} Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        write: `Create or completely overwrite a file inside an open workspace. The path is resolved within the workspace filesystem boundary. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        edit: `Edit one file inside an open workspace by replacing exact text blocks. Each oldText must match a unique, non-overlapping region of the original file. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
-        applyPatch: `Apply one Codex-style patch inside an open workspace. Supports adding, overwriting, updating, deleting, and moving files. Paths must be relative to the workspace. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        read: `Read a file inside an open workspace or the OS temp directory. Instruction files returned by ${toolNames.openWorkspace} and advertised skill files are also readable when applicable.${skillCapability} Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        write: `Create or completely overwrite a file inside an open workspace or the OS temp directory. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        edit: `Edit one file inside an open workspace or the OS temp directory by replacing exact text blocks. Each oldText must match a unique, non-overlapping region of the original file. Workspace paths may be relative; OS temp paths may be absolute. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
+        applyPatch: `Apply one Codex-style patch inside an open workspace or the OS temp directory. Supports adding, overwriting, updating, deleting, and moving files. Workspace paths must remain relative; absolute paths are accepted only inside the OS temp directory. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         shell: `Run a shell command inside an open workspace.${shellSurface} Commands execute with the local user's authority; workspace filesystem containment does not make shell execution a sandbox. Do not use ${toolNames.shell} to create or modify project files; use ${toolNames.edit} or ${toolNames.write} for file changes. Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
@@ -37,13 +37,14 @@ function capabilityContractInstructions(config, context) {
         ? `When ${toolNames.openWorkspace} returns available skills and a task matches a skill, use ${toolNames.read} to read that skill's path before proceeding. Skill paths may be outside the workspace, but ${toolNames.read} only permits advertised SKILL.md files and files under already-loaded skill directories.`
         : "";
     const toolSurface = toolSurfaceInstructions(config);
+    const hooks = "When a ForgeRelay tool result reports Hook results, tell the user which meaningful hooks ran and whether they passed or blocked the operation. Do not claim the requested operation succeeded when a blocking hook prevented it.";
     const artifact = config.artifactsEnabled && context.artifactDownloadSupported
         ? "When the user supplies or generates a file that is not present on the ForgeRelay host, use download_artifact with its native file value, the existing workspace ID, and a suitable relative destination path chosen from the user's request and project structure. The tool refuses to overwrite an existing destination and returns the normalized workspace-relative path. Use normal workspace tools when explicit inspection, replacement, movement, renaming, or deletion is needed. Do not recreate binary files with write/edit calls or place signed URLs, native file objects, base64 content, or invented host paths in shell commands or logs."
         : "";
     const showChanges = config.widgets === "changes"
         ? "If the turn successfully modifies files by creating, editing, overwriting, deleting, moving, or applying patches, call show_changes exactly once for that workspace after the final related file change and before your final response so the user can inspect the aggregate diff for that turn. Do not call it after every individual file change; do not skip it because individual file-change tools already returned diffs."
         : "";
-    return joinInstructions(workspaceLifecycle, agents, skills, toolSurface, artifact, showChanges);
+    return joinInstructions(workspaceLifecycle, agents, skills, toolSurface, hooks, artifact, showChanges);
 }
 function toolSurfaceInstructions(config) {
     if (config.toolMode === "codex") {

package/dist/pi-tools.js

@@ -1,5 +1,5 @@
 import { createBashTool, createEditTool, createFindTool, createGrepTool, createLsTool, createReadTool, createWriteTool, } from "@earendil-works/pi-coding-agent";
-import { resolveAllowedPath } from "./roots.js";
+import { resolveCanonicalAllowedPath } from "./roots.js";
 function toMcpContent(result) {
     return result.content.map((content) => {
         if (content.type === "text") {
@@ -29,7 +29,7 @@ async function runTool(execute, input, context) {
     }
 }
 export async function readFileTool(input, context) {
-    const path = resolveAllowedPath(input.path, context.cwd, context.readRoots ?? [context.root]);
+    const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.readRoots ?? [context.root]);
     const tool = createReadTool(context.cwd);
     return runTool((params) => tool.execute("read_file", params), {
         path,
@@ -38,7 +38,7 @@ export async function readFileTool(input, context) {
     }, context);
 }
 export async function writeFileTool(input, context) {
-    const path = resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.fileRoots ?? [context.root]);
     const tool = createWriteTool(context.cwd);
     return runTool((params) => tool.execute("write_file", params), {
         path,
@@ -46,7 +46,7 @@ export async function writeFileTool(input, context) {
     }, context);
 }
 export async function editFileTool(input, context) {
-    const path = resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = await resolveCanonicalAllowedPath(input.path, context.cwd, context.fileRoots ?? [context.root]);
     const tool = createEditTool(context.cwd);
     return runTool((params) => tool.execute("edit_file", params), {
         path,
@@ -54,22 +54,23 @@ export async function editFileTool(input, context) {
     }, context);
 }
 export async function grepFilesTool(input, context) {
-    if (input.path)
-        resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = input.path
+        ? await resolveCanonicalAllowedPath(input.path, context.cwd, context.fileRoots ?? [context.root])
+        : undefined;
     const tool = createGrepTool(context.cwd);
-    return runTool((params) => tool.execute("grep_files", params), input, context);
+    return runTool((params) => tool.execute("grep_files", params), { ...input, path }, context);
 }
 export async function findFilesTool(input, context) {
-    if (input.path)
-        resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = input.path
+        ? await resolveCanonicalAllowedPath(input.path, context.cwd, context.fileRoots ?? [context.root])
+        : undefined;
     const tool = createFindTool(context.cwd);
-    return runTool((params) => tool.execute("find_files", params), input, context);
+    return runTool((params) => tool.execute("find_files", params), { ...input, path }, context);
 }
 export async function listDirectoryTool(input, context) {
-    if (input.path)
-        resolveAllowedPath(input.path, context.cwd, [context.root]);
+    const path = await resolveCanonicalAllowedPath(input.path ?? ".", context.cwd, context.fileRoots ?? [context.root]);
     const tool = createLsTool(context.cwd);
-    return runTool((params) => tool.execute("list_directory", params), input, context);
+    return runTool((params) => tool.execute("list_directory", params), { ...input, path }, context);
 }
 export async function runShellTool(input, context) {
     const tool = createBashTool(context.cwd);

package/dist/process-platform.js

@@ -18,6 +18,7 @@ export function resolveShellCommand(command, platform = process.platform, enviro
         return {
             executable: environment.ComSpec ?? environment.COMSPEC ?? "cmd.exe",
             args: ["/d", "/s", "/c", command],
+            windowsVerbatimArguments: true,
         };
     }
     const configuredShell = environment.SHELL;

package/dist/roots.js

@@ -1,5 +1,6 @@
+import { realpath } from "node:fs/promises";
 import { homedir } from "node:os";
-import { isAbsolute, relative, resolve, sep } from "node:path";
+import { basename, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 export class AccessDeniedError extends Error {
     constructor(message) {
         super(message);
@@ -35,3 +36,31 @@ export function resolveAllowedPath(inputPath, cwd, allowedRoots) {
     const absolutePath = resolve(cwd, inputPath);
     return assertAllowedPath(absolutePath, allowedRoots);
 }
+export async function resolveCanonicalAllowedPath(inputPath, cwd, allowedRoots) {
+    const absolutePath = resolveAllowedPath(inputPath, cwd, allowedRoots);
+    const canonicalPath = await canonicalizePath(absolutePath);
+    const canonicalRoots = await Promise.all(allowedRoots.map((root) => canonicalizePath(resolve(expandHomePath(root)))));
+    if (canonicalRoots.some((root) => isPathInsideRoot(canonicalPath, root))) {
+        return absolutePath;
+    }
+    throw new AccessDeniedError(`Path is outside allowed roots: ${inputPath}`);
+}
+async function canonicalizePath(path) {
+    const missingSegments = [];
+    let candidate = path;
+    while (true) {
+        try {
+            return resolve(await realpath(candidate), ...missingSegments.slice().reverse());
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "ENOENT" && code !== "ENOTDIR")
+                throw error;
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return resolve(path);
+            missingSegments.push(basename(candidate));
+            candidate = parent;
+        }
+    }
+}