@akira-tl/forgerelay 0.6.0 → 0.6.2

package/CHANGELOG.md

@@ -4,6 +4,42 @@ 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
+
+- Added Workspace Relay: register a remote ForgeRelay with `forgerelay auth`, then open a remote Workspace through the existing MCP surface with `open_workspace(..., relay="<alias>")`; direct targets and system-SSH-routed targets share the same authentication and MCP protocol.
+- Added CLI remote authentication with hidden owner-token input, explicit `--token`, and SSH-assisted `--ssh-auth`; `-J` accepts one final SSH target or a full comma-separated jump route while the remote service target remains one independent `host:port`/URL value.
+- Added remote routing for Workspace reads and mutations, Bash/process lifecycle and durable output, optional capabilities, Skills, Hooks, and Host Activity snapshot/detail/output queries while keeping execution facts owned by the execution ForgeRelay.
+- Added restart-safe remote identity and Workspace routing: stable remote instance IDs survive alias/target changes, access tokens refresh through the existing token store, SSH tunnels are rebuilt on fresh random loopback ports, and relayed Workspace IDs remain stable across Gateway restarts.
+
+### Changed
+
+- Activity Panel bootstrap can reconstruct Workspace presentation from the execution instance across independent MCP connections, allowing relayed Host Turns and App-only Activity queries to follow the execution Workspace without requiring one long-lived transport session.
+- ForgeRelay authentication and relayed-Workspace route files now use lock-protected read/modify/write updates with atomic replacement so concurrent CLI/server sessions do not overwrite each other.
+
+### Security
+
+- Remote targets, SSH routes, temporary tunnel ports, owner tokens, access tokens, refresh tokens, and execution-side Workspace IDs stay out of the model-facing relay contract; the Host sees the configured relay alias and Gateway `rws_...` identity instead.
+- SSH-assisted authentication retrieves the remote owner token only into the initiating process, then reuses the normal CLI token exchange; runtime forwarding binds loopback only, and failed direct/SSH/remote operations never silently fall back to a local or different remote Workspace.
+
 ## [0.6.0] - 2026-08-27
 
 ### 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
@@ -158,7 +196,7 @@ You can rebase and verify inside the worktree, then retry the close.
 
 Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一个文件：全局放在 `~/.forgerelay/hooks/<hook-name>.json`，项目放在 `<repo>/.forgerelay/hooks/<hook-name>.json`。文件名就是 Hook 名，方便直接从目录看出每条规则的用途；全局与项目规则组合执行，不需要额外批准。
 
-例如项目里的 `.forgerelay/hooks/release-tag-local-ci.json` 可以要求稳定版本 tag push 前先完成本地发布检查：
+例如项目里的 `.forgerelay/hooks/release-tag-gate.json` 可以在稳定版本 tag push 前执行轻量发布门禁：
 
 ```json
 {
@@ -173,7 +211,7 @@ Hook 是 ForgeRelay 的自动生命周期规则。首选方式是一个 Hook 一
 }
 ```
 
-耗时的 `npm run release:verify` 应先在已提交的 release-ready HEAD 上运行，它会写入绑定 HEAD/package version 的本地 release proof。命中 `BeforeTool` 后，Hook 只快速验证该 proof、clean working tree（含 untracked）与 tag 指向；成功才继续原始 `git push`，失败则直接阻断。这样发布 gate 不依赖一个持续数分钟的 MCP 请求。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
+命中 `BeforeTool` 后，Hook 只快速验证 clean working tree（含 untracked）、tag 与 package version 一致，以及本地 tag 指向当前 HEAD；成功才继续原始 `git push`，失败则直接阻断。Hook 不运行、也不要求本地 CI。tag 推送后由 GitHub Actions 的 Linux/macOS/Windows 矩阵执行权威验证，全部通过后才进入发布。`npm run release:verify` 仅作为可选的本地云端复现工具。Hook 结果会回到 Agent，Agent 应向用户说明重要 Hook 是否通过或阻断了操作。`report:false` 可以隐藏不重要的成功报告，但阻断失败始终可见。
 
 旧的 inline `hooks` 和聚合 `hooks.json` 仍兼容；新配置建议都用独立 `hooks/*.json` 文件。
 
@@ -293,18 +331,15 @@ npm run release:check
 npm run release:patch
 npm run release:minor
 npm run release:major
-npm run release:verify
 ```
 
-Daily branch pushes do not run cloud CI. When preparing a release, commit the
-release-ready tree and run the full local release verification on that clean HEAD.
-`release:verify` includes a focused parity pass in an isolated Node 22.19.0 environment
-with its own `npm ci`, matching the cloud CI runtime for native addons and high-risk
-LSP lifecycle tests, then writes the local proof consumed by the tag-push Hook. Pushing a matching
-`vX.Y.Z` tag to `Akira-TL/forgerelay` is the only cloud CI and publish trigger:
-GitHub Actions runs the reusable multi-platform CI, then publishes
-`@akira-tl/forgerelay` and creates the matching GitHub Release only after CI
-succeeds.
+Daily branch pushes do not run cloud CI. Commit the release-ready tree, push it to
+`main`, then push the matching `vX.Y.Z` tag. That tag is the only cloud CI and publish
+trigger: GitHub Actions runs the reusable Linux/macOS/Windows verification matrix,
+then publishes `@akira-tl/forgerelay` and creates the matching GitHub Release only
+after all platforms succeed. `npm run release:verify` remains available only when a
+cloud failure needs local reproduction against the pinned Node runtime; it is not a
+release prerequisite.
 
 See [Versioning and Release Management](docs/versioning.md) for the bootstrap and
 Trusted Publishing setup.

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(),
@@ -42,7 +43,7 @@ const snapshotOutputSchema = {
     activities: z.array(activitySummarySchema),
     [ACTIVITY_PANEL_WORKSPACE_META_KEY]: z.record(z.string(), z.unknown()).optional(),
 };
-export function registerActivityQueryTools(server, queries, connectionScopeId, panelMeta = {}, panelDefaultExpanded = false, logging, workspacePanelState) {
+export function registerActivityQueryTools(server, queries, connectionScopeId, panelMeta = {}, panelDefaultExpanded = false, logging, workspacePanelState, relay) {
     const panelUi = typeof panelMeta.ui === "object" && panelMeta.ui !== null
         ? panelMeta.ui
         : {};
@@ -69,7 +70,23 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         if (!workspace) {
             throw new Error(`No Workspace presentation is available for ${workspaceId}. Call open_workspace for that workspace before activity_panel.`);
         }
-        const snapshot = queries.beginTurn(hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId), workspaceId);
+        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const relayed = await relay?.panel(workspaceId, conversationScopeId);
+        if (relayed) {
+            return {
+                ...relayed,
+                _meta: {
+                    ...(relayed._meta ?? {}),
+                    [ACTIVITY_PANEL_DEFAULT_EXPANDED_META_KEY]: panelDefaultExpanded,
+                    [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                },
+                structuredContent: {
+                    ...(relayed.structuredContent ?? {}),
+                    [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                },
+            };
+        }
+        const snapshot = queries.beginTurn(conversationScopeId, workspaceId);
         if (logging) {
             logEvent(logging, "debug", "activity_panel_call", {
                 turnId: snapshot.turnId,
@@ -108,6 +125,27 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, workspaceId, knownRevision }, extra) => {
         const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const relayed = await relay?.snapshot({ turnId, workspaceId, knownRevision }, conversationScopeId);
+        if (relayed) {
+            const workspace = workspaceId ? workspacePanelState?.(workspaceId) : undefined;
+            if (workspaceId && !workspace) {
+                throw new Error(`No Workspace presentation is available for ${workspaceId}.`);
+            }
+            return workspace
+                ? {
+                    ...relayed,
+                    _meta: {
+                        ...(relayed._meta ?? {}),
+                        [ACTIVITY_PANEL_DEFAULT_EXPANDED_META_KEY]: panelDefaultExpanded,
+                        [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                    },
+                    structuredContent: {
+                        ...(relayed.structuredContent ?? {}),
+                        [ACTIVITY_PANEL_WORKSPACE_META_KEY]: workspace,
+                    },
+                }
+                : relayed;
+        }
         const resolvedTurnId = turnId ?? queries.currentTurnId(conversationScopeId, workspaceId);
         if (!resolvedTurnId) {
             throw new Error("Activity snapshot bootstrap could not resolve the current Host Turn from conversation and workspace metadata.");
@@ -162,6 +200,10 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         _meta: { ui: { visibility: ["app"] } },
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, activityId }, extra) => {
+        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const relayed = await relay?.detail(turnId, activityId, conversationScopeId);
+        if (relayed)
+            return relayed;
         const detail = queries.detail(turnId, activityId);
         if (logging) {
             logEvent(logging, "debug", "activity_detail_call", {
@@ -201,6 +243,10 @@ export function registerActivityQueryTools(server, queries, connectionScopeId, p
         _meta: { ui: { visibility: ["app"] } },
         annotations: READ_ONLY_ANNOTATIONS,
     }, async ({ turnId, outputId }, extra) => {
+        const conversationScopeId = hostConversationScopeId(extra._meta, extra.sessionId, connectionScopeId);
+        const relayed = await relay?.output(turnId, outputId, conversationScopeId);
+        if (relayed)
+            return relayed;
         const output = queries.bashOutput(turnId, outputId);
         if (logging) {
             logEvent(logging, "debug", "activity_output_call", {

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/cli.js

@@ -18,10 +18,12 @@ import { isLocalAgentProvider, loadLocalAgentProfiles, } from "./local-agent-pro
 import { assertLocalAgentProviderAvailable, formatLocalAgentProviderAvailabilitySummary, } from "./local-agent-availability.js";
 import { formatAvailableLocalAgentTargets, parseLocalAgentRunArgs, resolveLocalAgentTarget, } from "./local-agent-targets.js";
 import { createLocalAgentStore } from "./local-agent-store.js";
-import { generateOwnerToken, loadDevspaceFiles, resolveSubagentsFlag, writeDevspaceAuth, writeDevspaceConfig, } from "./user-config.js";
+import { ensureForgeRelayInstanceId, generateInstanceId, generateOwnerToken, loadDevspaceFiles, removeForgeRelayRemote, renameForgeRelayRemote, resolveSubagentsFlag, writeDevspaceAuth, writeDevspaceConfig, writeForgeRelayRemote, } from "./user-config.js";
 import { expandHomePath } from "./roots.js";
 import { shutdownHttpServer } from "./server-shutdown.js";
 import { publicEndpointUrl } from "./oauth/public-url.js";
+import { authenticateRemote, defaultRemoteAlias, isRemoteMcpUnauthorized, normalizeRemoteServiceTarget, refreshRemoteAuthentication, verifyRemoteMcp, } from "./remote-auth.js";
+import { defaultSshRouteAlias, parseSshRoute, readRemoteOwnerToken, withRemoteServiceEndpoint, } from "./remote-transport.js";
 const require = createRequire(import.meta.url);
 const SUPPORTED_NODE_RANGE = ">=20.12 <27";
 async function main(argv) {
@@ -48,6 +50,9 @@ async function main(argv) {
         case "agents":
             await runAgentsCommand(args);
             return;
+        case "auth":
+            await runAuthCommand(args);
+            return;
         case "help":
             printHelp();
             return;
@@ -59,7 +64,7 @@ async function main(argv) {
 function normalizeCommand(command) {
     if (!command || command === "serve" || command === "start")
         return "serve";
-    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents")
+    if (command === "init" || command === "doctor" || command === "config" || command === "hooks" || command === "agents" || command === "auth")
         return command;
     if (command === "help" || command === "--help" || command === "-h")
         return "help";
@@ -69,10 +74,14 @@ function normalizeCommand(command) {
 }
 async function ensureConfigured() {
     const files = loadDevspaceFiles();
-    if (files.configExists && files.authExists)
+    if (files.configExists && files.authExists) {
+        ensureForgeRelayInstanceId();
         return;
-    if (process.env.FORGERELAY_OAUTH_OWNER_TOKEN ?? process.env.DEVSPACE_OAUTH_OWNER_TOKEN)
+    }
+    if (process.env.FORGERELAY_OAUTH_OWNER_TOKEN ?? process.env.DEVSPACE_OAUTH_OWNER_TOKEN) {
+        ensureForgeRelayInstanceId();
         return;
+    }
     if (!input.isTTY || !output.isTTY) {
         throw new Error([
             "ForgeRelay is not configured and this terminal is non-interactive.",
@@ -143,7 +152,9 @@ async function runInit({ force }) {
             subagents: resolveSubagentsFlag(files.config),
         };
         const auth = {
+            ...files.auth,
             ownerToken: files.auth.ownerToken ?? generateOwnerToken(),
+            instanceId: files.auth.instanceId ?? generateInstanceId(),
         };
         const configPath = writeDevspaceConfig(config);
         const authPath = writeDevspaceAuth(auth);
@@ -214,6 +225,166 @@ async function serve() {
     process.once("SIGINT", handleShutdown);
     process.once("SIGTERM", handleShutdown);
 }
+function parseAuthCommandArgs(args) {
+    let target;
+    let alias;
+    let ownerToken;
+    let sshRoute;
+    let sshAuth = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (arg === "--alias") {
+            alias = args[++index];
+            if (!alias)
+                throw new Error("Missing value for --alias.");
+            continue;
+        }
+        if (arg === "--token") {
+            ownerToken = args[++index];
+            if (!ownerToken)
+                throw new Error("Missing value for --token.");
+            continue;
+        }
+        if (arg === "-J") {
+            const route = args[++index];
+            if (!route)
+                throw new Error("Missing value for -J.");
+            sshRoute = parseSshRoute(route);
+            continue;
+        }
+        if (arg === "--ssh-auth") {
+            sshAuth = true;
+            continue;
+        }
+        if (arg.startsWith("-"))
+            throw new Error(`Unknown auth option: ${arg}`);
+        if (target)
+            throw new Error(`Unexpected auth argument: ${arg}`);
+        target = arg;
+    }
+    if (!target)
+        throw new Error("Missing remote service target.");
+    if (sshAuth && !sshRoute)
+        throw new Error("--ssh-auth requires -J <ssh-route>.");
+    if (sshAuth && ownerToken)
+        throw new Error("--ssh-auth and --token cannot be used together.");
+    return { target, alias, ownerToken, sshRoute, sshAuth };
+}
+async function resolveAuthOwnerToken(ownerToken) {
+    if (ownerToken)
+        return ownerToken;
+    if (!input.isTTY || !output.isTTY) {
+        throw new Error("Missing owner token. Pass --token, use --ssh-auth with -J, or run in an interactive terminal.");
+    }
+    const result = await prompts.password({
+        message: "Remote ForgeRelay owner token",
+        validate: (value) => value?.trim() ? undefined : "Enter the remote owner token.",
+    });
+    if (prompts.isCancel(result))
+        throw new Error("Remote authentication cancelled.");
+    return String(result);
+}
+function localOwnerToken() {
+    const token = process.env.FORGERELAY_OAUTH_OWNER_TOKEN
+        ?? process.env.DEVSPACE_OAUTH_OWNER_TOKEN
+        ?? loadDevspaceFiles().auth.ownerToken;
+    if (!token)
+        throw new Error("ForgeRelay owner token is not configured on this machine.");
+    return token;
+}
+async function runAuthCommand(args) {
+    const [subcommand, ...rest] = args;
+    if (subcommand === "__owner-token") {
+        if (rest.length > 0)
+            throw new Error("Internal owner-token command does not accept arguments.");
+        process.stdout.write(`${localOwnerToken()}\n`);
+        return;
+    }
+    if (subcommand === "list") {
+        if (rest.length > 0)
+            throw new Error("forgerelay auth list does not accept additional arguments.");
+        const remotes = loadDevspaceFiles().auth.remotes ?? {};
+        if (Object.keys(remotes).length === 0) {
+            console.log("No remote ForgeRelay instances registered.");
+            return;
+        }
+        for (const [alias, remote] of Object.entries(remotes).sort(([left], [right]) => left.localeCompare(right))) {
+            console.log(`${alias}\t${remote.target}\t${remote.instanceId}`);
+        }
+        return;
+    }
+    if (subcommand === "rename") {
+        const [fromAlias, toAlias, ...extra] = rest;
+        if (!fromAlias || !toAlias || extra.length > 0) {
+            throw new Error("Usage: forgerelay auth rename <old-alias> <new-alias>");
+        }
+        renameForgeRelayRemote(fromAlias, toAlias);
+        console.log(`Renamed remote ${fromAlias} to ${toAlias}.`);
+        return;
+    }
+    if (subcommand === "remove") {
+        const [alias, ...extra] = rest;
+        if (!alias || extra.length > 0)
+            throw new Error("Usage: forgerelay auth remove <alias>");
+        removeForgeRelayRemote(alias);
+        console.log(`Removed remote ${alias}.`);
+        return;
+    }
+    if (subcommand === "test") {
+        const [alias, ...extra] = rest;
+        if (!alias || extra.length > 0)
+            throw new Error("Usage: forgerelay auth test <alias>");
+        const files = loadDevspaceFiles();
+        const storedRemote = files.auth.remotes?.[alias];
+        if (!storedRemote)
+            throw new Error(`Unknown remote alias: ${alias}`);
+        let remote = storedRemote;
+        await withRemoteServiceEndpoint(remote.target, remote.sshRoute, async (endpoint) => {
+            let refreshed = false;
+            if (remote.accessTokenExpiresAt <= Math.floor(Date.now() / 1000)) {
+                remote = await refreshRemoteAuthentication(remote, endpoint);
+                writeForgeRelayRemote(alias, remote);
+                refreshed = true;
+            }
+            try {
+                await verifyRemoteMcp(remote, endpoint);
+            }
+            catch (error) {
+                if (refreshed || !isRemoteMcpUnauthorized(error))
+                    throw error;
+                remote = await refreshRemoteAuthentication(remote, endpoint);
+                writeForgeRelayRemote(alias, remote);
+                await verifyRemoteMcp(remote, endpoint);
+            }
+        });
+        console.log(`${alias}\tok\t${remote.instanceId}`);
+        return;
+    }
+    const parsed = parseAuthCommandArgs(args);
+    const target = normalizeRemoteServiceTarget(parsed.target);
+    const authenticated = await withRemoteServiceEndpoint(target, parsed.sshRoute, async (endpoint) => {
+        const ownerToken = parsed.sshAuth
+            ? await readRemoteOwnerToken(parsed.sshRoute ?? [])
+            : await resolveAuthOwnerToken(parsed.ownerToken);
+        return authenticateRemote(endpoint, ownerToken);
+    });
+    const remote = {
+        ...authenticated,
+        target,
+        ...(parsed.sshRoute ? { sshRoute: parsed.sshRoute } : {}),
+    };
+    const files = loadDevspaceFiles();
+    const existingAlias = Object.entries(files.auth.remotes ?? {}).find(([, record]) => record.instanceId === remote.instanceId)?.[0];
+    const defaultAlias = parsed.sshRoute
+        ? defaultSshRouteAlias(parsed.sshRoute)
+        : defaultRemoteAlias(remote.target);
+    const alias = parsed.alias?.trim() || existingAlias || defaultAlias;
+    if (!files.auth.instanceId) {
+        ensureForgeRelayInstanceId();
+    }
+    writeForgeRelayRemote(alias, remote);
+    console.log(`Authenticated remote ${alias} (${remote.instanceId}).`);
+}
 async function runDoctor() {
     const files = loadDevspaceFiles();
     console.log(`Config dir: ${files.dir}`);
@@ -282,6 +453,12 @@ function printHelp() {
         "  forgerelay agents ls       List subagent sessions",
         "  forgerelay agents run <profile-or-provider-or-id> [--model <model>] <prompt>",
         "  forgerelay agents show <id>",
+        "  forgerelay auth <target> [--alias <name>] [--token <owner-token>]",
+        "  forgerelay auth -J <ssh-route> <target> [--alias <name>] [--token <owner-token>|--ssh-auth]",
+        "  forgerelay auth list",
+        "  forgerelay auth test <alias>",
+        "  forgerelay auth rename <old-alias> <new-alias>",
+        "  forgerelay auth remove <alias>",
         "  forgerelay -v, --version   Print the installed version",
         "",
         "For temporary tunnels:",

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