@akira-tl/forgerelay 0.2.4 → 0.2.6

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.2.6] - 2026-08-10
+
+### Changed
+
+- Running shell commands now expose canonical `processId` handles; `write_stdin` accepts `processId`, while the former process `sessionId` remains a deprecated compatibility alias throughout 0.2.x.
+- ForgeRelay now names protocol-level MCP state as a transport session in internal/debug terminology. Workspace identity remains `workspaceId`, one-request tracing remains `requestId`, and third-party provider session identifiers are unchanged.
+- Process elapsed time now uses a monotonic clock, preventing negative `wallTimeMs` values when the operating-system wall clock is adjusted while a long-running command or release Hook is executing.
+
+## [0.2.5] - 2026-08-10
+
+### Changed
+
+- Human-facing `pretty` logs are workspace-first: normal tool and hook lines no longer show transient MCP transport session IDs, MCP session create/close lifecycle events are debug-only, and project names receive stable per-project terminal colors while the logical `ws_...` identifier remains visible.
+- MCP App tool metadata now uses a content-hashed UI resource URI derived from the built JavaScript/CSS, advertises both `model` and `app` visibility, and includes the ChatGPT `openai/outputTemplate` compatibility alias. Legacy `ui://forgerelay/workspace-app.html` and historical `workspace-app-*.html` pointers continue to resolve to the current template so stale ChatGPT metadata snapshots do not fail with a missing resource. Debug logs now distinguish current, legacy, and historical template reads, and real acceptance exercises current/compatibility resources plus the referenced JavaScript asset.
+- `~/...` paths are expanded before allowed-root resolution, so advertised skills rendered with home-relative paths can be read directly instead of being interpreted as a literal `~` directory under the workspace.
+- Successful MCP session shutdown and idle-cleanup lifecycle logs moved to `debug`; individual session close failures remain visible as warnings.
+
 ## [0.2.4] - 2026-08-09
 
 ### Added

package/dist/artifact-tools.js

@@ -7,7 +7,7 @@ import * as z from "zod/v4";
 import { ArtifactError } from "./artifact-error.js";
 import { runToolWithHooks } from "./hooks.js";
 import { describeIncomingArtifactValue, IncomingArtifactAdapterRegistry, } from "./incoming-artifacts.js";
-import { logEvent, sessionIdPrefix, workspaceLogLabel } from "./logger.js";
+import { logEvent, workspaceLogLabel } from "./logger.js";
 const ARTIFACT_WRITE_ANNOTATIONS = {
     readOnlyHint: false,
     destructiveHint: false,
@@ -47,7 +47,7 @@ export function registerArtifactTools(server, { config, workspaces, hooks, incom
         },
         _meta: { "openai/fileParams": ["file"] },
         annotations: ARTIFACT_WRITE_ANNOTATIONS,
-    }, async (input, extra) => {
+    }, async (input) => {
         const workspace = workspaces.getWorkspace(input.workspaceId);
         return runToolWithHooks(hooks, {
             tool: "download_artifact",
@@ -61,7 +61,6 @@ export function registerArtifactTools(server, { config, workspaces, hooks, incom
             changedPaths: (result) => [result.structuredContent.path],
             operation: () => executeArtifactTool(config, input, {
                 workspace: workspaceLogLabel(workspace.root, workspace.id),
-                session: sessionIdPrefix(extra?.sessionId),
             }, async () => {
                 const downloaded = await downloadIncomingArtifact({
                     registry: incomingRegistry,

package/dist/logger.js

@@ -13,6 +13,14 @@ const LEVEL_STYLE = {
     info: "green",
     debug: "gray",
 };
+const WORKSPACE_PROJECT_COLORS = [
+    "cyanBright",
+    "greenBright",
+    "yellowBright",
+    "magentaBright",
+    "blueBright",
+    "whiteBright",
+];
 export function shouldLog(config, level) {
     return LEVEL_WEIGHT[config.level] >= LEVEL_WEIGHT[level];
 }
@@ -53,9 +61,11 @@ export function requestIp(req, trustProxy) {
 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)}`
@@ -70,12 +80,16 @@ 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 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)}]`,
-        style(["cyan", "underline"], source, options),
-        session ? style("gray", `session:${session}`, options) : undefined,
+        formatPrettySource(source, options),
+        transportSession ? style("gray", `transport:${transportSession}`, options) : undefined,
         style("gray", "|", options),
     ].filter((value) => Boolean(value)).join(" ");
     return `${prefix} ${formatPrettyMessage(entry, options)}`;
@@ -92,12 +106,24 @@ function formatPrettyMessage(entry, options) {
             return formatHookMessage(entry, options);
         case "http_request":
             return formatHttpMessage(entry, options);
+        case "mcp_request":
+            return formatMcpRequestMessage(entry);
+        case "mcp_app_template_read":
+            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} 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":
@@ -121,8 +147,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)) {
@@ -161,6 +187,42 @@ function formatHttpMessage(entry, options) {
     const statusStyle = status !== undefined && status >= 400 ? "red" : "green";
     return `http ${method} ${path} -> ${style(statusStyle, statusText, options)}`;
 }
+function formatMcpRequestMessage(entry) {
+    const method = stringField(entry.rpcMethod) ?? stringField(entry.httpMethod) ?? "request";
+    const target = stringField(entry.rpcTarget);
+    return target ? `mcp ${method} ${target}` : `mcp ${method}`;
+}
+function formatAppTemplateMessage(entry, options, failed) {
+    const requestedUri = stringField(entry.requestedUri) ?? "unknown";
+    const compatibility = stringField(entry.compatibility) ?? "unknown";
+    if (failed) {
+        const error = stringField(entry.error);
+        return `app template ${compatibility} ${requestedUri} -> ${style("red", error ? `error: ${error}` : "error", options)}`;
+    }
+    const currentUri = stringField(entry.currentUri);
+    const target = compatibility === "current" || !currentUri
+        ? requestedUri
+        : `${requestedUri} => ${currentUri}`;
+    return `app template ${compatibility} ${target} -> ${style("green", "ok", options)}`;
+}
+function formatPrettySource(source, options) {
+    const separator = source.lastIndexOf("/");
+    if (separator <= 0 || separator === source.length - 1) {
+        return style(["cyan", "underline"], source, options);
+    }
+    const project = source.slice(0, separator);
+    const workspace = source.slice(separator + 1);
+    const projectColor = WORKSPACE_PROJECT_COLORS[stableColorIndex(project)];
+    return `${style([projectColor, "bold"], project, options)}/${style(["cyan", "underline"], workspace, options)}`;
+}
+function stableColorIndex(value) {
+    let hash = 2166136261;
+    for (let index = 0; index < value.length; index += 1) {
+        hash ^= value.charCodeAt(index);
+        hash = Math.imul(hash, 16777619);
+    }
+    return (hash >>> 0) % WORKSPACE_PROJECT_COLORS.length;
+}
 function formatGenericMessage(entry) {
     const event = String(entry.event ?? "log");
     const detail = [entry.reason, entry.error]
@@ -181,6 +243,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

@@ -34,7 +34,7 @@ export function buildToolDescriptions(config) {
         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 for bash, then returns a running process with a processId without killing it; use ${toolNames.writeStdin} with that processId 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.`,
         shellCommand: "Shell command to run with the local user's authority.",
     };
 }
@@ -62,9 +62,9 @@ function toolSurfaceInstructions(config) {
         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 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 processes.`;
     }
-    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 `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 processes.`;
 }
 function selectedWorkflowInstructions(config) {
     if (config.workflowInstructions === false)
@@ -80,7 +80,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-app-template.js

@@ -0,0 +1,45 @@
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+export const WORKSPACE_APP_MANIFEST_ENTRY = "workspace-app.html";
+export const WORKSPACE_APP_LEGACY_URI = "ui://forgerelay/workspace-app.html";
+export const WORKSPACE_APP_URI_TEMPLATE = "ui://forgerelay/workspace-app-{revision}.html";
+export function workspaceAppUriForRevision(revision) {
+    return `ui://forgerelay/workspace-app-${encodeURIComponent(revision)}.html`;
+}
+export function readWorkspaceAppManifestEntry(manifestUrl) {
+    const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+    const entry = manifest[WORKSPACE_APP_MANIFEST_ENTRY];
+    if (!entry?.file) {
+        throw new Error(`Missing ${WORKSPACE_APP_MANIFEST_ENTRY} in UI manifest.`);
+    }
+    return entry;
+}
+export function workspaceAppBundleRevision(entry, buildDirectoryUrl) {
+    const hash = createHash("sha256");
+    const assetPaths = [entry.file, ...(entry.css ?? [])];
+    for (const assetPath of assetPaths) {
+        hash.update(assetPath);
+        hash.update("\0");
+        hash.update(readFileSync(new URL(assetPath, buildDirectoryUrl)));
+        hash.update("\0");
+    }
+    return hash.digest("hex").slice(0, 12);
+}
+export function resolveWorkspaceAppIdentity(options) {
+    try {
+        const entry = readWorkspaceAppManifestEntry(options.manifestUrl);
+        const revision = workspaceAppBundleRevision(entry, options.buildDirectoryUrl);
+        return {
+            revision,
+            uri: workspaceAppUriForRevision(revision),
+            source: "bundle",
+        };
+    }
+    catch {
+        return {
+            revision: options.fallbackRevision,
+            uri: workspaceAppUriForRevision(options.fallbackRevision),
+            source: "fallback",
+        };
+    }
+}

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 };