@akira-tl/forgerelay 0.2.5 → 0.3.0

package/dist/logger.js

@@ -47,23 +47,17 @@ export function logEvent(config, level, event, fields = {}) {
         console.log(line);
     }
 }
-export function requestIp(req, trustProxy) {
-    if (trustProxy) {
-        const cfConnectingIp = firstHeaderValue(req.header("cf-connecting-ip"));
-        if (cfConnectingIp)
-            return cfConnectingIp;
-        const forwardedFor = firstHeaderValue(req.header("x-forwarded-for"));
-        if (forwardedFor)
-            return forwardedFor;
-    }
+export function requestIp(req) {
     return req.ip ?? req.socket.remoteAddress;
 }
 export function requestPath(req) {
     return req.path || req.url.split("?")[0] || req.url;
 }
-export function sessionIdPrefix(sessionId) {
-    return sessionId ? sessionId.slice(0, 8) : undefined;
+export function transportSessionIdPrefix(transportSessionId) {
+    return transportSessionId ? transportSessionId.slice(0, 8) : undefined;
 }
+/** @deprecated Use transportSessionIdPrefix. */
+export const sessionIdPrefix = transportSessionIdPrefix;
 export function workspaceLogLabel(root, workspaceId) {
     const shortWorkspaceId = workspaceId.startsWith("ws_")
         ? `ws_${workspaceId.slice(3, 11)}`
@@ -78,21 +72,20 @@ 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 = level === "debug"
-        ? stringField(entry.session) ?? stringField(entry.sessionIdPrefix)
+    const transportSession = level === "debug"
+        ? stringField(entry.transportSessionIdPrefix)
+            ?? stringField(entry.session)
+            ?? stringField(entry.sessionIdPrefix)
         : undefined;
     const prefix = [
         style("gray", time, options),
         `[${style(LEVEL_STYLE[level], level.toUpperCase(), options)}]`,
         formatPrettySource(source, options),
-        session ? style("gray", `session:${session}`, options) : undefined,
+        transportSession ? style("gray", `transport:${transportSession}`, 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 formatPrettyMessage(entry, options) {
     switch (String(entry.event)) {
         case "tool_call":
@@ -108,14 +101,18 @@ function formatPrettyMessage(entry, options) {
             return formatAppTemplateMessage(entry, options, false);
         case "mcp_app_template_read_failed":
             return formatAppTemplateMessage(entry, options, true);
+        case "mcp_transport_session_created":
         case "mcp_session_created":
-            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} created`;
+            return `transport session ${transportSessionPrefix(entry) ?? "unknown"} created`;
+        case "mcp_transport_session_closed":
         case "mcp_session_closed":
-            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} closed`;
+            return `transport session ${transportSessionPrefix(entry) ?? "unknown"} closed`;
+        case "mcp_transport_sessions_closed":
         case "mcp_sessions_closed":
-            return `${numberField(entry.count) ?? 0} sessions closed`;
+            return `${numberField(entry.count) ?? 0} transport sessions closed`;
+        case "mcp_transport_session_close_failed":
         case "mcp_session_close_failed":
-            return `session ${stringField(entry.sessionIdPrefix) ?? "unknown"} close -> ${style("red", "error", options)}`;
+            return `transport session ${transportSessionPrefix(entry) ?? "unknown"} close -> ${style("red", "error", options)}`;
         case "auth_denied":
             return `auth denied${entry.reason ? `: ${String(entry.reason)}` : ""}`;
         case "mcp_request_error":
@@ -139,8 +136,8 @@ function toolTarget(entry, tool) {
 }
 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 processId = entry.processId ?? entry.processSessionId;
+        return style("yellow", processId === undefined ? "running" : `running process:${String(processId)}`, options);
     }
     const exitCode = numberField(entry.exitCode) ?? exitCodeFromError(entry.error);
     if (isShellTool(tool)) {
@@ -235,6 +232,11 @@ function logLevel(value) {
 function stringField(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+function transportSessionPrefix(entry) {
+    return stringField(entry.transportSessionIdPrefix)
+        ?? stringField(entry.sessionIdPrefix)
+        ?? stringField(entry.session);
+}
 function numberField(value) {
     return typeof value === "number" && Number.isFinite(value) ? value : undefined;
 }

package/dist/mcp/server-instructions.js

@@ -14,57 +14,42 @@ export const toolNames = {
     writeStdin: "write_stdin",
 };
 export function buildShellMutationPolicy() {
-    return "Shell commands may modify ordinary project files when that is a natural part of the user's requested development task. Never use shell commands to modify security- or privilege-sensitive operating-system files or credential material such as /etc/sudoers, /etc/passwd, /etc/shadow, PAM or authentication policy, SSH private keys, or equivalent privileged system files. Modify configuration files through shell only when the user's request explicitly calls for that configuration change; do not infer permission merely because changing configuration would be convenient.";
+    return "Shell commands may modify ordinary project files when that is a natural part of the user's requested development task. They may also perform external device or hardware mutations when the user's current request explicitly asks for the actual device-changing operation, including firmware flashing or equivalent persistent device updates; do not infer such authorization from a check, audit, probe, backup, verification, dry-run, or build-only request. Never use shell commands to modify security- or privilege-sensitive operating-system files or credential material such as /etc/sudoers, /etc/passwd, /etc/shadow, PAM or authentication policy, SSH private keys, or equivalent privileged system files. Modify configuration files through shell only when the user's request explicitly calls for that configuration change; do not infer permission merely because changing configuration would be convenient.";
 }
-export function buildServerInstructions(config, context = {}) {
-    return joinInstructions(capabilityContractInstructions(config, context), selectedWorkflowInstructions(config), config.appendInstructions);
+export function buildServerInstructions(config) {
+    return joinInstructions(capabilityContractInstructions(config), selectedWorkflowInstructions(config), config.appendInstructions);
 }
 export function buildToolDescriptions(config) {
     const skillCapability = config.skillsEnabled
-        ? " Advertised skill paths may be outside the workspace; only advertised SKILL.md files and files under already-loaded skill directories are readable."
+        ? " Advertised skill paths may also be outside the workspace."
         : "";
     const shellSurface = config.toolMode === "minimal"
         ? ` 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.`
         : "";
-    const shellMutationPolicy = buildShellMutationPolicy();
     return {
-        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.`,
+        read: `Read a file inside an open workspace or the OS temp directory. Instruction files and advertised capability guides returned by ${toolNames.openWorkspace} are also readable when applicable.${skillCapability} Only advertised entry files and files under already-loaded advertised directories are readable outside the normal roots. 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.`,
         rename: `Rename or move one file or directory inside an open workspace or the OS temp directory without overwriting an existing destination. Source and destination must both remain inside the permitted file roots. Call ${toolNames.openWorkspace} first and pass workspaceId.`,
         delete: `Delete one file or directory inside an open workspace or the OS temp directory. Non-empty directories require recursive=true. An allowed root itself cannot be deleted. 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. ForgeRelay waits up to 300 seconds for bash, then returns a running process session without killing it; use ${toolNames.writeStdin} to poll, keep waiting, interact, or send Ctrl-C. Completed background commands are also reported with a later tool result for the same workspaceId. ${shellMutationPolicy} Call ${toolNames.openWorkspace} first and pass workspaceId. This capability should only be exposed behind strong authentication.`,
+        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. ForgeRelay waits up to 300 seconds, then returns a processId for a still-running command; use ${toolNames.writeStdin} to poll, interact, wait, or send Ctrl-C. Completed background commands may be reported later for the same workspaceId. Call ${toolNames.openWorkspace} first and pass workspaceId. Expose this capability only behind strong authentication.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }
-function capabilityContractInstructions(config, context) {
-    const workspaceLifecycle = config.toolMode === "codex"
-        ? `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Keep the workspaceId returned for this conversation stable. Different conversations normally receive separate logical workspaceIds even when they point at the same physical checkout or worktree; pass an existing workspaceId to ${toolNames.openWorkspace} only when the user wants to resume that logical workspace in this conversation. Only request a new logical workspace when the user explicitly asks. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`
-        : `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Keep the workspaceId returned for this conversation stable for later file, search, edit, write, rename, delete, show-changes, shell, and process-polling tools. Different conversations normally receive separate logical workspaceIds even when they point at the same physical checkout or worktree; pass an existing workspaceId to ${toolNames.openWorkspace} only when the user wants to resume that logical workspace in this conversation. Only request a new logical workspace when the user explicitly asks. If ${toolNames.openWorkspace} reports logical workspaces idle for more than two days, tell the user each workspaceId and let them decide whether to resume it or explicitly clean it up with ${toolNames.closeWorkspace}; do not close it automatically. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. Managed worktrees use dedicated forgerelay/* branches, not detached HEADs. When work in a managed worktree is complete and verified, call ${toolNames.closeWorktree}; it commits remaining worktree changes, fast-forwards the original target branch only when safe, then removes the worktree and its branch. If the target branch diverged or the source checkout is dirty, closing is refused and the worktree is preserved.`;
-    const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Before working under a path listed in availableAgentsFiles, use ${toolNames.read} to inspect that instruction file and follow it.`;
+function capabilityContractInstructions(config) {
+    const staleWorkspacePolicy = config.toolMode === "codex"
+        ? ""
+        : ` If ${toolNames.openWorkspace} reports logical workspaces idle for more than two days, let the user choose whether to resume or close them with ${toolNames.closeWorkspace}; never close them automatically.`;
+    const workspaceLifecycle = `Use ForgeRelay as a local coding workspace. Default to the user's existing checkout. Reuse the workspaceId returned by ${toolNames.openWorkspace} for this conversation; resume another logical workspaceId only when the user wants that workspace, and request a new logical workspace only when explicitly asked.${staleWorkspacePolicy} Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel Git work. ${toolNames.closeWorkspace} releases a logical workspace; ${toolNames.closeWorktree} finalizes a managed worktree. Read the managed-worktrees capability guide for advanced worktree lifecycle and failure semantics.`;
+    const agents = `Follow instructions returned by ${toolNames.openWorkspace}. Read an availableAgentsFiles path before working under it.`;
+    const capabilityGuides = `When ${toolNames.openWorkspace} returns capability guides, use ${toolNames.read} to load only a task-relevant guide; do not preload all guides.`;
     const skills = config.skillsEnabled
-        ? `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.`
+        ? `When a task matches an available skill from ${toolNames.openWorkspace}, read its advertised path before proceeding. Outside normal file roots, ${toolNames.read} permits only advertised entry files and files under already-loaded advertised directories.`
         : "";
-    const toolSurface = toolSurfaceInstructions(config);
     const shellMutationPolicy = buildShellMutationPolicy();
     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, shellMutationPolicy, hooks, artifact, showChanges);
-}
-function toolSurfaceInstructions(config) {
-    if (config.toolMode === "codex") {
-        return `In codex tool mode, workspace file and command operations use ${toolNames.read}, ${toolNames.rename}, ${toolNames.delete}, apply_patch, exec_command, and ${toolNames.writeStdin}.`;
-    }
-    if (config.toolMode === "full") {
-        return `In full tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are available alongside the core workspace tools. ${toolNames.writeStdin} is available for running bash sessions.`;
-    }
-    return `In minimal tool mode, dedicated ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} inspection tools are disabled; the core workspace tools remain available, including ${toolNames.writeStdin} for running bash sessions.`;
+    return joinInstructions(workspaceLifecycle, agents, capabilityGuides, skills, shellMutationPolicy, hooks);
 }
 function selectedWorkflowInstructions(config) {
     if (config.workflowInstructions === false)
@@ -80,7 +65,7 @@ function defaultWorkflowInstructions(config) {
     const inspection = config.toolMode === "full"
         ? `Prefer ${toolNames.read}, ${toolNames.grep}, ${toolNames.glob}, and ${toolNames.ls} for file inspection.`
         : `Use ${toolNames.shell} with command-line tools such as grep, rg, find, ls, and tree for search and directory inspection.`;
-    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, generators, formatters, and commands that are better executed by the shell. If ${toolNames.shell} returns a running session, use ${toolNames.writeStdin} only when you need to poll, wait, interact, or interrupt it; otherwise you may continue other work and consume its completion notice from a later tool result.`);
+    return joinInstructions(inspection, `Prefer ${toolNames.edit} for targeted content modifications, ${toolNames.write} only for new files or complete rewrites, ${toolNames.rename} for path moves, ${toolNames.delete} for removals, and ${toolNames.shell} for tests, builds, git inspection, package scripts, generators, formatters, and commands that are better executed by the shell. If ${toolNames.shell} returns a running process with a processId, use ${toolNames.writeStdin} only when you need to poll, wait, interact, or interrupt it; otherwise you may continue other work and consume its completion notice from a later tool result.`);
 }
 function joinInstructions(...parts) {
     return parts

package/dist/mcp-sessions.js

@@ -1,56 +1,58 @@
-export class McpSessionRegistry {
-    sessions = new Map();
+export class McpTransportRegistry {
+    transports = new Map();
     now;
     constructor(options = {}) {
         this.now = options.now ?? Date.now;
     }
     get size() {
-        return this.sessions.size;
+        return this.transports.size;
     }
-    register(sessionId, transport) {
-        this.sessions.set(sessionId, {
+    register(transportSessionId, transport) {
+        this.transports.set(transportSessionId, {
             transport,
             lastActivityAt: this.now(),
         });
     }
-    get(sessionId) {
-        const entry = this.sessions.get(sessionId);
+    get(transportSessionId) {
+        const entry = this.transports.get(transportSessionId);
         if (!entry)
             return undefined;
         entry.lastActivityAt = this.now();
         return entry.transport;
     }
-    remove(sessionId) {
-        return this.sessions.delete(sessionId);
+    remove(transportSessionId) {
+        return this.transports.delete(transportSessionId);
     }
     async closeIdle(idleTimeoutMs) {
         const cutoff = this.now() - idleTimeoutMs;
-        const idleSessions = [];
-        for (const [sessionId, entry] of this.sessions) {
+        const idleTransports = [];
+        for (const [transportSessionId, entry] of this.transports) {
             if (entry.lastActivityAt > cutoff)
                 continue;
-            this.sessions.delete(sessionId);
-            idleSessions.push({ sessionId, transport: entry.transport });
+            this.transports.delete(transportSessionId);
+            idleTransports.push({ transportSessionId, transport: entry.transport });
         }
-        return closeSessions(idleSessions);
+        return closeTransports(idleTransports);
     }
     async closeAll() {
-        const sessions = Array.from(this.sessions, ([sessionId, entry]) => ({
-            sessionId,
+        const transports = Array.from(this.transports, ([transportSessionId, entry]) => ({
+            transportSessionId,
             transport: entry.transport,
         }));
-        this.sessions.clear();
-        return closeSessions(sessions);
+        this.transports.clear();
+        return closeTransports(transports);
     }
 }
-async function closeSessions(sessions) {
-    return Promise.all(sessions.map(async ({ sessionId, transport }) => {
+async function closeTransports(transports) {
+    return Promise.all(transports.map(async ({ transportSessionId, transport }) => {
         try {
             await transport.close();
-            return { sessionId };
+            return { transportSessionId };
         }
         catch (error) {
-            return { sessionId, error };
+            return { transportSessionId, error };
         }
     }));
 }
+/** @deprecated Use McpTransportRegistry. */
+export { McpTransportRegistry as McpSessionRegistry };