@akira-tl/forgerelay 0.6.1 → 0.6.2

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.6.2] - 2026-08-29
+
+### Added
+
+- Added Composite Workspace as a first-class Workspace kind on the existing `open_workspace` surface. A Composite Workspace has its own persistent `cws_...` identity, may start with zero members, and can mount named local, managed-worktree, or relayed Workspaces with Agent-facing purpose descriptions.
+- Added explicit member routing across filesystem, capability, Bash/process, and Codex-compatible `apply_patch` / `exec_command` / `write_stdin` surfaces. The Composite Workspace ID remains Host-facing while each operation must name its execution member; ForgeRelay never selects or falls back to another member automatically.
+- Added one Composite Host Turn / Activity presentation that aggregates local and remote member activity with member labels while keeping audit, process, filesystem, and remote execution facts owned by the actual member Workspace/Execution ForgeRelay.
+
+### Changed
+
+- `close_workspace` now dissolves a Composite Workspace without closing member Workspaces, finalizing managed worktrees, interrupting member processes, deleting files, or removing Workspace Relay routes.
+- Interactive debug launchers now derive their displayed local endpoints from the selected `FORGERELAY_DEBUG_CONFIG_DIR/config.json`, allowing multiple isolated debug instances to use separate config/state/worktree directories and different ports such as 7677 and 6768.
+
+### Fixed
+
+- Routed Codex-compatible process and patch tools through the same Workspace Relay and Composite member resolution path as the canonical tool surface, including explicit no-fallback behavior for remote members.
+
 ## [0.6.1] - 2026-08-28
 
 ### Added

package/README.md

@@ -101,6 +101,44 @@ Once a workspace is open, the host can:
 Normal work happens in your existing checkout. ForgeRelay does not silently move
 every task into a worktree.
 
+## Composite workspaces across multiple devices
+
+When one task needs more than one execution environment, a Composite Workspace keeps
+one Host-facing working context while preserving each member Workspace as a separate
+execution boundary. For example, `code` can point at a local checkout while
+`compute` points through Workspace Relay at a GPU machine.
+
+Composite Workspaces use the same lifecycle entry points as ordinary Workspaces:
+
+```text
+open_workspace({ kind: "composite", name: "research-project" })
+open_workspace({
+  action: "member",
+  workspaceId: "cws_...",
+  memberAction: "add",
+  member: {
+    name: "compute",
+    purpose: "GPU and high-performance computation",
+    path: "/srv/research",
+    relay: "gpu-server"
+  }
+})
+```
+
+Work still names the member explicitly:
+
+```text
+read({ workspaceId: "cws_...", member: "code", path: "src/model.py" })
+bash({ workspaceId: "cws_...", member: "compute", command: "python train.py" })
+```
+
+ForgeRelay does not merge member filesystems, Git state, Hooks, Skills, processes,
+or audit facts, and it never infers a member from the tool type or purpose text.
+The Composite Activity Panel presents member operations in one Host Turn while the
+actual facts remain owned by the member Workspace. `close_workspace` on a Composite
+Workspace means **dissolve**: the Composite identity and membership are removed, but
+member Workspaces, worktrees, running jobs, files, and relay routes are preserved.
+
 ### Progressive MCP context
 
 ForgeRelay keeps the callable MCP surface and its low-frequency operating manuals

package/dist/activity/mcp-query-tools.js

@@ -20,6 +20,7 @@ const activitySummarySchema = z.object({
     target: z.string(),
     detailAvailable: z.boolean(),
     workspaceId: z.string().optional(),
+    member: z.string().optional(),
     processId: z.number().int().positive().optional(),
     outputId: z.string().optional(),
     commandLength: z.number().int().nonnegative().optional(),

package/dist/activity/query-service.js

@@ -126,6 +126,7 @@ function toSummary(record) {
         target: activityTarget(record, request, result, structured),
         detailAvailable: !bulkGroup && record.tool !== "rename" && record.tool !== "delete" && record.tool !== "batch",
         ...(record.workspace.id ? { workspaceId: record.workspace.id } : {}),
+        ...(stringField(request, "member") ? { member: stringField(request, "member") } : {}),
         ...(processId !== undefined ? { processId } : {}),
         ...(outputId !== undefined ? { outputId } : {}),
         ...(bashLike && command !== undefined ? { commandLength: command.length } : {}),

package/dist/composite-activity.js

@@ -0,0 +1,155 @@
+export class CompositeActivityCoordinator {
+    composites;
+    queries;
+    remoteWorkspaces;
+    turns = new Map();
+    constructor(composites, queries, remoteWorkspaces) {
+        this.composites = composites;
+        this.queries = queries;
+        this.remoteWorkspaces = remoteWorkspaces;
+    }
+    hasComposite(workspaceId) {
+        return this.composites.has(workspaceId);
+    }
+    beginPanel(workspaceId, conversationScopeId) {
+        this.composites.open(workspaceId);
+        const snapshot = this.queries.beginTurn(conversationScopeId, workspaceId);
+        this.turns.set(snapshot.turnId, {
+            compositeWorkspaceId: workspaceId,
+            conversationScopeId,
+            remoteMembers: new Map(),
+            remoteActivities: new Map(),
+            remoteOutputs: new Map(),
+        });
+        return snapshotResult(snapshot, `Started Composite Workspace Host Turn ${snapshot.turnId}.`);
+    }
+    currentTurnId(conversationScopeId, compositeWorkspaceId) {
+        const turnId = this.queries.currentTurnId(conversationScopeId, compositeWorkspaceId);
+        return turnId && this.turns.has(turnId) ? turnId : undefined;
+    }
+    async prepareMember(compositeWorkspaceId, member, executionWorkspaceId, conversationScopeId) {
+        const turnId = this.currentTurnId(conversationScopeId, compositeWorkspaceId);
+        if (!turnId)
+            return undefined;
+        if (!this.remoteWorkspaces.has(executionWorkspaceId))
+            return turnId;
+        const state = this.turns.get(turnId);
+        const existing = state.remoteMembers.get(member);
+        if (existing?.workspaceId === executionWorkspaceId)
+            return turnId;
+        const panel = await this.remoteWorkspaces.activityPanel(executionWorkspaceId, conversationScopeId);
+        const remoteTurnId = requiredString(panel.structuredContent, "turnId", "Remote Activity panel");
+        state.remoteMembers.set(member, {
+            member,
+            workspaceId: executionWorkspaceId,
+            remoteTurnId,
+        });
+        return turnId;
+    }
+    async snapshot(turnId, knownRevision) {
+        const state = this.turns.get(turnId);
+        if (!state)
+            return undefined;
+        const local = this.queries.snapshot(turnId);
+        const remoteSnapshots = await Promise.all([...state.remoteMembers.values()].map(async (route) => ({
+            route,
+            snapshot: await this.remoteWorkspaces.activitySnapshot({ turnId: route.remoteTurnId }, state.conversationScopeId),
+        })));
+        state.remoteActivities.clear();
+        state.remoteOutputs.clear();
+        const remoteActivities = [];
+        let revision = local.revision;
+        for (const { route, snapshot } of remoteSnapshots) {
+            if (!snapshot?.structuredContent)
+                continue;
+            const structured = snapshot.structuredContent;
+            const remoteRevision = structured.revision;
+            if (typeof remoteRevision === "number" && Number.isInteger(remoteRevision) && remoteRevision >= 0) {
+                revision += remoteRevision;
+            }
+            const activities = Array.isArray(structured.activities)
+                ? structured.activities
+                : [];
+            for (const activity of activities) {
+                const presented = { ...activity, member: route.member };
+                remoteActivities.push(presented);
+                state.remoteActivities.set(activity.activityId, route);
+                if (activity.outputId)
+                    state.remoteOutputs.set(activity.outputId, route);
+            }
+        }
+        const activities = [...local.activities, ...remoteActivities]
+            .sort((left, right) => left.startedAt.localeCompare(right.startedAt));
+        const changed = knownRevision === undefined || knownRevision !== revision;
+        const snapshot = {
+            turnId,
+            revision,
+            changed,
+            state: aggregateState(activities),
+            activities: changed ? activities : [],
+        };
+        return snapshotResult(snapshot, changed
+            ? `Composite Activity snapshot ${turnId} revision ${revision}.`
+            : `Composite Activity snapshot ${turnId} unchanged at revision ${revision}.`);
+    }
+    async detail(turnId, activityId) {
+        const state = this.turns.get(turnId);
+        if (!state)
+            return undefined;
+        const route = state.remoteActivities.get(activityId);
+        if (!route)
+            return undefined;
+        const result = await this.remoteWorkspaces.activityDetail(route.remoteTurnId, activityId, state.conversationScopeId);
+        if (!result?.structuredContent)
+            return result;
+        const structured = result.structuredContent;
+        const activity = structured.activity;
+        return {
+            ...result,
+            structuredContent: {
+                ...structured,
+                ...(activity && typeof activity === "object"
+                    ? { activity: { ...activity, member: route.member } }
+                    : {}),
+            },
+        };
+    }
+    async output(turnId, outputId) {
+        const state = this.turns.get(turnId);
+        if (!state)
+            return undefined;
+        const route = state.remoteOutputs.get(outputId);
+        if (!route)
+            return undefined;
+        return this.remoteWorkspaces.activityOutput(route.remoteTurnId, outputId, state.conversationScopeId);
+    }
+    forgetComposite(workspaceId) {
+        for (const [turnId, state] of this.turns) {
+            if (state.compositeWorkspaceId === workspaceId)
+                this.turns.delete(turnId);
+        }
+    }
+}
+function snapshotResult(snapshot, text) {
+    return {
+        content: [{ type: "text", text }],
+        structuredContent: snapshot,
+    };
+}
+function aggregateState(activities) {
+    if (activities.length === 0)
+        return "working";
+    if (activities.some((activity) => activity.status === "working"))
+        return "working";
+    if (activities.some((activity) => activity.status === "error"))
+        return "error";
+    return "done";
+}
+function requiredString(value, field, label) {
+    if (!value || typeof value !== "object")
+        throw new Error(`${label} did not return structured content.`);
+    const fieldValue = value[field];
+    if (typeof fieldValue !== "string" || !fieldValue)
+        throw new Error(`${label} did not include ${field}.`);
+    return fieldValue;
+}

package/dist/composite-workspaces.js

@@ -0,0 +1,197 @@
+import { randomBytes } from "node:crypto";
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+export class CompositeWorkspaceRegistry {
+    stateDir;
+    statePath;
+    records = new Map();
+    constructor(stateDir) {
+        this.stateDir = stateDir;
+        this.statePath = join(stateDir, "composite-workspaces.json");
+        this.load();
+    }
+    has(workspaceId) {
+        return this.records.has(workspaceId);
+    }
+    create(name) {
+        const normalized = normalizeName(name);
+        const existing = [...this.records.values()].find((record) => record.name === normalized);
+        if (existing)
+            return this.touch(existing.id);
+        const now = new Date().toISOString();
+        const record = {
+            id: `cws_${randomBytes(5).toString("hex")}`,
+            kind: "composite",
+            name: normalized,
+            members: [],
+            createdAt: now,
+            lastUsedAt: now,
+        };
+        this.records.set(record.id, record);
+        this.persist();
+        return cloneRecord(record);
+    }
+    get(workspaceId) {
+        const record = this.records.get(workspaceId);
+        if (!record)
+            throw new Error(`Unknown Composite Workspace ${workspaceId}.`);
+        return cloneRecord(record);
+    }
+    open(workspaceId) {
+        return this.touch(workspaceId);
+    }
+    list() {
+        return [...this.records.values()]
+            .map(cloneRecord)
+            .sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt));
+    }
+    addMember(workspaceId, input) {
+        const record = this.requireRecord(workspaceId);
+        const name = normalizeMemberName(input.name);
+        const purpose = input.purpose.trim();
+        if (!purpose)
+            throw new Error("Composite Workspace member purpose must not be empty.");
+        const existing = record.members.find((member) => member.name === name);
+        if (existing) {
+            if (existing.purpose === purpose && existing.workspaceId === input.workspaceId) {
+                return cloneRecord(record);
+            }
+            throw new Error(`Composite Workspace ${workspaceId} already has member ${name} with a different definition.`);
+        }
+        record.members.push({ name, purpose, workspaceId: input.workspaceId });
+        record.lastUsedAt = new Date().toISOString();
+        this.persist();
+        return cloneRecord(record);
+    }
+    updateMember(workspaceId, memberName, input) {
+        const record = this.requireRecord(workspaceId);
+        const currentName = normalizeMemberName(memberName);
+        const index = record.members.findIndex((member) => member.name === currentName);
+        if (index < 0)
+            throw new Error(`Composite Workspace ${workspaceId} has no member ${currentName}.`);
+        const current = record.members[index];
+        const nextName = input.name === undefined ? current.name : normalizeMemberName(input.name);
+        const nextPurpose = input.purpose === undefined ? current.purpose : input.purpose.trim();
+        if (!nextPurpose)
+            throw new Error("Composite Workspace member purpose must not be empty.");
+        const nextWorkspaceId = input.workspaceId ?? current.workspaceId;
+        if (nextName !== current.name &&
+            record.members.some((member, memberIndex) => memberIndex !== index && member.name === nextName)) {
+            throw new Error(`Composite Workspace ${workspaceId} already has member ${nextName}.`);
+        }
+        if (nextName === current.name &&
+            nextPurpose === current.purpose &&
+            nextWorkspaceId === current.workspaceId) {
+            return cloneRecord(record);
+        }
+        record.members[index] = {
+            name: nextName,
+            purpose: nextPurpose,
+            workspaceId: nextWorkspaceId,
+        };
+        record.lastUsedAt = new Date().toISOString();
+        this.persist();
+        return cloneRecord(record);
+    }
+    removeMember(workspaceId, memberName) {
+        const record = this.requireRecord(workspaceId);
+        const name = normalizeMemberName(memberName);
+        const index = record.members.findIndex((member) => member.name === name);
+        if (index < 0)
+            throw new Error(`Composite Workspace ${workspaceId} has no member ${name}.`);
+        record.members.splice(index, 1);
+        record.lastUsedAt = new Date().toISOString();
+        this.persist();
+        return cloneRecord(record);
+    }
+    member(workspaceId, memberName) {
+        const record = this.requireRecord(workspaceId);
+        const name = normalizeMemberName(memberName);
+        const member = record.members.find((entry) => entry.name === name);
+        if (!member)
+            throw new Error(`Composite Workspace ${workspaceId} has no member ${name}.`);
+        return { ...member };
+    }
+    dissolve(workspaceId) {
+        const record = this.requireRecord(workspaceId);
+        this.records.delete(workspaceId);
+        this.persist();
+        return cloneRecord(record);
+    }
+    touch(workspaceId) {
+        const record = this.requireRecord(workspaceId);
+        record.lastUsedAt = new Date().toISOString();
+        this.persist();
+        return cloneRecord(record);
+    }
+    requireRecord(workspaceId) {
+        const record = this.records.get(workspaceId);
+        if (!record)
+            throw new Error(`Unknown Composite Workspace ${workspaceId}.`);
+        return record;
+    }
+    load() {
+        let parsed;
+        try {
+            parsed = JSON.parse(readFileSync(this.statePath, "utf8"));
+        }
+        catch (error) {
+            if (isMissingFile(error))
+                return;
+            throw new Error(`Failed to load Composite Workspace state: ${errorMessage(error)}`);
+        }
+        if (parsed?.version !== 1 || !Array.isArray(parsed.workspaces)) {
+            throw new Error("Composite Workspace state has an unsupported format.");
+        }
+        for (const record of parsed.workspaces) {
+            if (!record?.id?.startsWith("cws_") || record.kind !== "composite")
+                continue;
+            this.records.set(record.id, {
+                ...record,
+                members: Array.isArray(record.members) ? record.members.map((member) => ({ ...member })) : [],
+            });
+        }
+    }
+    persist() {
+        mkdirSync(this.stateDir, { recursive: true });
+        const state = {
+            version: 1,
+            workspaces: [...this.records.values()].map(cloneRecord),
+        };
+        const tempPath = `${this.statePath}.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
+        try {
+            writeFileSync(tempPath, `${JSON.stringify(state, null, 2)}\n`, { mode: 0o600 });
+            renameSync(tempPath, this.statePath);
+        }
+        finally {
+            rmSync(tempPath, { force: true });
+        }
+    }
+}
+function normalizeName(name) {
+    const value = name.trim();
+    if (!value)
+        throw new Error("Composite Workspace name must not be empty.");
+    if (value.length > 120)
+        throw new Error("Composite Workspace name must be at most 120 characters.");
+    return value;
+}
+function normalizeMemberName(name) {
+    const value = name.trim();
+    if (!/^[a-z][a-z0-9_-]{0,31}$/.test(value)) {
+        throw new Error("Composite Workspace member name must match /^[a-z][a-z0-9_-]{0,31}$/.");
+    }
+    return value;
+}
+function cloneRecord(record) {
+    return {
+        ...record,
+        members: record.members.map((member) => ({ ...member })),
+    };
+}
+function isMissingFile(error) {
+    return error instanceof Error && "code" in error && error.code === "ENOENT";
+}
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/remote-workspace-relay.js

@@ -101,6 +101,13 @@ export class RemoteWorkspaceRelay {
             instruction: `${remoteInstruction}\nThis workspace executes on remote ${alias}.`,
         };
     }
+    async resumeWorkspace(gatewayWorkspaceId, context = "auto", conversationScopeId) {
+        const result = await this.callWorkspaceTool(gatewayWorkspaceId, "open_workspace", { context }, conversationScopeId);
+        if (result.isError === true) {
+            throw new Error(`Remote open_workspace failed: ${toolResultText(result)}`);
+        }
+        return result;
+    }
     async read(gatewayWorkspaceId, input, conversationScopeId) {
         return this.callWorkspaceTool(gatewayWorkspaceId, "read", input, conversationScopeId);
     }
@@ -119,6 +126,15 @@ export class RemoteWorkspaceRelay {
     async bash(gatewayWorkspaceId, input, conversationScopeId) {
         return this.callWorkspaceTool(gatewayWorkspaceId, "bash", input, conversationScopeId);
     }
+    async execCommand(gatewayWorkspaceId, input, conversationScopeId) {
+        return this.callWorkspaceTool(gatewayWorkspaceId, "exec_command", input, conversationScopeId);
+    }
+    async writeStdin(gatewayWorkspaceId, input, conversationScopeId) {
+        return this.callWorkspaceTool(gatewayWorkspaceId, "write_stdin", input, conversationScopeId);
+    }
+    async applyPatch(gatewayWorkspaceId, input, conversationScopeId) {
+        return this.callWorkspaceTool(gatewayWorkspaceId, "apply_patch", input, conversationScopeId);
+    }
     async capability(gatewayWorkspaceId, input, conversationScopeId) {
         return this.callWorkspaceTool(gatewayWorkspaceId, "capability", input, conversationScopeId);
     }