@akira-tl/forgerelay 0.2.2 → 0.2.4

package/CHANGELOG.md

@@ -4,6 +4,31 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.2.4] - 2026-08-09
+
+### Added
+
+- Conversation-scoped logical workspace handles: the same conversation keeps a stable `workspaceId`, different conversations normally receive separate IDs for the same physical checkout/worktree, `open_workspace` can explicitly resume a known ID or allocate a user-requested fresh logical handle, and workspaces idle for more than two days are reported for user-directed resumption or cleanup.
+- `close_workspace` releases a logical workspace handle without deleting checkout files; the last handle anchoring a physical worktree remains protected for `close_worktree`.
+
+### Changed
+
+- `bash` now uses ForgeRelay's process-session runtime instead of the Pi bash executor. It waits in the foreground for at most 300 seconds and, if still running, returns a `sessionId` without killing the process. `write_stdin` is available in regular tool modes to poll, wait, interact, or interrupt, and asynchronous completion is delivered once on a later tool result for the same workspace ID.
+
+### Security
+
+- Background-process ownership and completion delivery are scoped to the logical `workspaceId`; logical workspace cleanup is refused while that ID owns a running or unconsumed process completion, and idle-session scanning does not refresh stale activity timestamps.
+
+## [0.2.3] - 2026-08-09
+
+### Changed
+
+- Shell tools no longer carry a blanket prohibition against commands that modify files. `bash` and Codex `exec_command` may update ordinary project files when that is a natural part of the user's requested development task, including package managers, generators, and formatters.
+
+### Security
+
+- The Agent shell contract continues to prohibit mutation of security- or privilege-sensitive operating-system files and credential material such as `/etc/sudoers`, `/etc/passwd`, `/etc/shadow`, authentication policy, and SSH private keys; configuration-file changes through shell require an explicit user request.
+
 ## [0.2.2] - 2026-08-09
 
 ### Added

package/dist/hooks.js

@@ -92,6 +92,12 @@ export function parseHookConfig(value) {
     }
     return config;
 }
+function decorateToolResult(runner, workspaceId, result) {
+    const decorator = runner.decorateResult;
+    return workspaceId && typeof decorator === "function"
+        ? decorator.call(runner, workspaceId, result)
+        : result;
+}
 export async function runToolWithHooks(runner, options) {
     const basePayload = { tool: options.tool, ...(options.payload ?? {}) };
     const executions = [];
@@ -108,7 +114,8 @@ export async function runToolWithHooks(runner, options) {
                 cwd: afterCwd,
                 payload: basePayload,
             }));
-            return attachHookReports(result, executions);
+            const reported = attachHookReports(result, executions);
+            return decorateToolResult(runner, options.invocation.workspaceId, reported);
         }
         executions.push(...await runner.run("AfterTool", {
             ...options.invocation,
@@ -123,7 +130,8 @@ export async function runToolWithHooks(runner, options) {
                 payload: { ...basePayload, paths: changedPaths },
             }));
         }
-        return attachHookReports(result, executions);
+        const reported = attachHookReports(result, executions);
+        return decorateToolResult(runner, options.invocation.workspaceId, reported);
     }
     catch (error) {
         if (error instanceof HookExecutionError) {
@@ -136,7 +144,8 @@ export async function runToolWithHooks(runner, options) {
                 errorType: error instanceof Error ? error.name : "Error",
             },
         }));
-        throw appendHookReportsToError(error, executions);
+        const reportedError = appendHookReportsToError(error, executions);
+        throw decorateToolResult(runner, options.invocation.workspaceId, reportedError);
     }
 }
 export function attachHookReports(result, executions) {
@@ -188,10 +197,15 @@ export class HookRunner {
     hooks;
     logging;
     baseEnv;
-    constructor(hooks, logging, baseEnv = process.env) {
+    resultDecorator;
+    constructor(hooks, logging, baseEnv = process.env, resultDecorator) {
         this.hooks = hooks;
         this.logging = logging;
         this.baseEnv = baseEnv;
+        this.resultDecorator = resultDecorator;
+    }
+    decorateResult(workspaceId, result) {
+        return (this.resultDecorator?.(workspaceId, result) ?? result);
     }
     async run(event, invocation) {
         const projectRoot = event === "AfterWorktreeClose" && invocation.sourceRoot

package/dist/mcp/server-instructions.js

@@ -1,5 +1,6 @@
 export const toolNames = {
     openWorkspace: "open_workspace",
+    closeWorkspace: "close_workspace",
     closeWorktree: "close_worktree",
     read: "read",
     write: "write",
@@ -10,7 +11,11 @@ export const toolNames = {
     glob: "glob",
     ls: "ls",
     shell: "bash",
+    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.";
+}
 export function buildServerInstructions(config, context = {}) {
     return joinInstructions(capabilityContractInstructions(config, context), selectedWorkflowInstructions(config), config.appendInstructions);
 }
@@ -21,6 +26,7 @@ export function buildToolDescriptions(config) {
     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.`,
         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.`,
@@ -28,19 +34,20 @@ 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. Do not use ${toolNames.shell} to create, move, rename, or delete project files; use ${toolNames.edit}, ${toolNames.write}, ${toolNames.rename}, or ${toolNames.delete} for file changes. 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 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.`,
         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 and reuse its workspaceId. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel 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 and reuse its workspaceId for later file, search, edit, write, rename, delete, show-changes, and shell tools. Only open mode=\"worktree\" when the user explicitly asks for isolated or parallel 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. 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.`;
     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.`
         : "";
     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."
@@ -48,16 +55,16 @@ function capabilityContractInstructions(config, context) {
     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, hooks, artifact, showChanges);
+    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 write_stdin.`;
+        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.`;
+        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.`;
+    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.`;
 }
 function selectedWorkflowInstructions(config) {
     if (config.workflowInstructions === false)
@@ -68,12 +75,12 @@ function selectedWorkflowInstructions(config) {
 }
 function defaultWorkflowInstructions(config) {
     if (config.toolMode === "codex") {
-        return `Use ${toolNames.read} for direct file reads, ${toolNames.rename} and ${toolNames.delete} for direct path moves or removals, apply_patch for content modifications, exec_command for inspection, tests, builds, and other commands, and write_stdin to poll or interact with running processes.`;
+        return `Use ${toolNames.read} for direct file reads, ${toolNames.rename} and ${toolNames.delete} for direct path moves or removals, apply_patch for content modifications, exec_command for inspection, tests, builds, and other commands, and ${toolNames.writeStdin} to poll or interact with running processes.`;
     }
     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, and commands that are better executed by the shell.`, `Do not create or modify files with ${toolNames.shell}; avoid shell redirection, heredocs, tee, sed -i, perl -i, node/python/ruby scripts, or any command whose purpose is to write project files.`);
+    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.`);
 }
 function joinInstructions(...parts) {
     return parts

package/dist/pi-tools.js

@@ -1,4 +1,4 @@
-import { createBashTool, createEditTool, createFindTool, createGrepTool, createLsTool, createReadTool, createWriteTool, } from "@earendil-works/pi-coding-agent";
+import { createEditTool, createFindTool, createGrepTool, createLsTool, createReadTool, createWriteTool, } from "@earendil-works/pi-coding-agent";
 import { resolveCanonicalAllowedPath } from "./roots.js";
 function toMcpContent(result) {
     return result.content.map((content) => {
@@ -72,11 +72,3 @@ export async function listDirectoryTool(input, context) {
     const tool = createLsTool(context.cwd);
     return runTool((params) => tool.execute("list_directory", params), { ...input, path }, context);
 }
-export async function runShellTool(input, context) {
-    const tool = createBashTool(context.cwd);
-    const timeout = input.timeout === undefined ? 30 : Math.min(input.timeout, 300);
-    return runTool((params) => tool.execute("run_shell", params), {
-        command: input.command,
-        timeout,
-    }, context);
-}

package/dist/process-sessions.js

@@ -3,11 +3,12 @@ import { resolveShellCommand, terminateProcessTree } from "./process-platform.js
 const DEFAULT_EXEC_YIELD_MS = 10_000;
 const DEFAULT_INTERACTIVE_YIELD_MS = 250;
 const DEFAULT_POLL_YIELD_MS = 5_000;
-const MAX_COMMAND_YIELD_MS = 30_000;
-const MAX_POLL_YIELD_MS = 110_000;
+const MAX_START_YIELD_MS = 300_000;
+const MAX_COMMAND_YIELD_MS = 300_000;
+const MAX_POLL_YIELD_MS = 300_000;
 const DEFAULT_MAX_OUTPUT_TOKENS = 10_000;
 const DEFAULT_BUFFER_CHARACTERS = 1_000_000;
-const COMPLETED_SESSION_TTL_MS = 5 * 60 * 1_000;
+const COMPLETED_SESSION_TTL_MS = 24 * 60 * 60 * 1_000;
 const DEFAULT_COLUMNS = 80;
 const DEFAULT_ROWS = 24;
 function boundedInteger(value, fallback, maximum) {
@@ -28,13 +29,13 @@ function terminalSize(value, fallback) {
 }
 function processEnvironment(input) {
     return {
-        ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined)),
+        ...Object.fromEntries(Object.entries(process.env).filter((entry) => entry[1] !== undefined && (input?.codexCi || entry[0] !== "CODEX_CI"))),
         NO_COLOR: "1",
         TERM: "dumb",
         PAGER: "cat",
         GIT_PAGER: "cat",
         GH_PAGER: "cat",
-        CODEX_CI: "1",
+        ...(input?.codexCi ? { CODEX_CI: "1" } : {}),
         LANG: process.env.LANG ?? "C.UTF-8",
         LC_ALL: process.env.LC_ALL ?? "C.UTF-8",
         ...(input?.workspaceId ? { FORGERELAY_WORKSPACE_ID: input.workspaceId, DEVSPACE_WORKSPACE_ID: input.workspaceId } : {}),
@@ -130,12 +131,15 @@ function truncateOutput(output, maxCharacters) {
 }
 export class ProcessSessionManager {
     sessions = new Map();
+    completedByWorkspace = new Map();
     maxBufferCharacters;
     completedSessionTtlMs;
+    maxStartYieldMs;
     nextSessionId = 1;
     constructor(options = {}) {
         this.maxBufferCharacters = options.maxBufferCharacters ?? DEFAULT_BUFFER_CHARACTERS;
         this.completedSessionTtlMs = options.completedSessionTtlMs ?? COMPLETED_SESSION_TTL_MS;
+        this.maxStartYieldMs = options.maxStartYieldMs ?? MAX_START_YIELD_MS;
     }
     async start(input) {
         const session = this.createSession(input);
@@ -150,10 +154,12 @@ export class ProcessSessionManager {
             this.sessions.delete(session.id);
             throw error;
         }
-        const yieldTimeMs = boundedInteger(input.yieldTimeMs, DEFAULT_EXEC_YIELD_MS, MAX_COMMAND_YIELD_MS);
+        const yieldTimeMs = boundedInteger(input.yieldTimeMs, DEFAULT_EXEC_YIELD_MS, this.maxStartYieldMs);
         await this.waitForExit(session, yieldTimeMs);
+        if (session.running)
+            session.background = true;
         const snapshot = this.consume(session, input.maxOutputTokens);
-        if (!session.running)
+        if (!snapshot.running)
             this.removeSession(session.id);
         return snapshot;
     }
@@ -187,6 +193,26 @@ export class ProcessSessionManager {
             this.removeSession(session.id);
         return snapshot;
     }
+    activeWorkspaceIds() {
+        return new Set([...this.sessions.values()].map((session) => session.workspaceId));
+    }
+    takeCompleted(workspaceId, maxOutputTokens, excludeSessionId) {
+        const sessionIds = this.completedByWorkspace.get(workspaceId) ?? [];
+        if (sessionIds.length === 0)
+            return [];
+        const completed = [];
+        for (const sessionId of sessionIds) {
+            if (sessionId === excludeSessionId)
+                continue;
+            const session = this.sessions.get(sessionId);
+            if (!session || session.running)
+                continue;
+            const snapshot = this.consume(session, maxOutputTokens);
+            completed.push({ ...snapshot, sessionId: session.id, command: session.command });
+            this.removeSession(session.id);
+        }
+        return completed;
+    }
     terminate(workspaceId, sessionId) {
         const session = this.getOwnedSession(workspaceId, sessionId);
         if (session.running)
@@ -200,6 +226,7 @@ export class ProcessSessionManager {
                 session.process?.kill("SIGTERM");
         }
         this.sessions.clear();
+        this.completedByWorkspace.clear();
     }
     async waitForExit(session, yieldTimeMs) {
         let timer;
@@ -224,11 +251,13 @@ export class ProcessSessionManager {
         return {
             id: this.nextSessionId++,
             workspaceId: input.workspaceId,
+            command: input.command,
             startedAt: Date.now(),
             columns: terminalSize(input.columns, DEFAULT_COLUMNS),
             rows: terminalSize(input.rows, DEFAULT_ROWS),
             buffer: new HeadTailBuffer(this.maxBufferCharacters),
             running: true,
+            background: false,
             exitPromise,
             resolveExit,
         };
@@ -241,6 +270,7 @@ export class ProcessSessionManager {
             env: processEnvironment({
                 workspaceId: input.workspaceId,
                 workspaceRoot: input.workspaceRoot,
+                codexCi: input.codexCi,
             }),
             stdio: "pipe",
             windowsHide: true,
@@ -273,6 +303,7 @@ export class ProcessSessionManager {
                 env: processEnvironment({
                     workspaceId: input.workspaceId,
                     workspaceRoot: input.workspaceRoot,
+                    codexCi: input.codexCi,
                 }),
                 name: "xterm-256color",
                 cols: session.columns,
@@ -299,7 +330,14 @@ export class ProcessSessionManager {
         session.exitCode = exitCode;
         session.signal = signal;
         session.resolveExit();
-        session.cleanupTimer = setTimeout(() => this.sessions.delete(session.id), this.completedSessionTtlMs);
+        if (session.background) {
+            const completed = this.completedByWorkspace.get(session.workspaceId) ?? [];
+            if (!completed.includes(session.id)) {
+                completed.push(session.id);
+                this.completedByWorkspace.set(session.workspaceId, completed);
+            }
+        }
+        session.cleanupTimer = setTimeout(() => this.removeSession(session.id), this.completedSessionTtlMs);
         session.cleanupTimer.unref();
     }
     append(session, output) {
@@ -333,5 +371,15 @@ export class ProcessSessionManager {
         if (session?.cleanupTimer)
             clearTimeout(session.cleanupTimer);
         this.sessions.delete(sessionId);
+        if (!session)
+            return;
+        const completed = this.completedByWorkspace.get(session.workspaceId);
+        if (!completed)
+            return;
+        const remaining = completed.filter((id) => id !== sessionId);
+        if (remaining.length > 0)
+            this.completedByWorkspace.set(session.workspaceId, remaining);
+        else
+            this.completedByWorkspace.delete(session.workspaceId);
     }
 }