golutra-mcp 0.1.1 → 0.1.3

package/.env.example

@@ -2,7 +2,11 @@
 # install paths for `golutra-cli`, then falls back to the platform command
 # name from PATH (`golutra-cli.exe` on Windows, `golutra-cli` elsewhere).
 GOLUTRA_CLI_PATH=golutra-cli
-GOLUTRA_PROFILE=stable
+# Optional. If profile/host are unset, runtime search order is:
+# stable:desktop, stable:server(web), dev:desktop, dev:server(web).
+GOLUTRA_PROFILE=
+GOLUTRA_CLI_HOST_KIND=
+GOLUTRA_TARGET_ORDER=
 GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
 GOLUTRA_COMMAND_TIMEOUT_MS=30000
 

package/CHANGELOG.md

@@ -6,6 +6,30 @@ The format follows Keep a Changelog, and this project uses Semantic Versioning.
 
 ## [Unreleased]
 
+## [0.1.3] - 2026-05-01
+
+### Added
+
+- Added focused MCP tools for Golutra team creation, member configuration, conversations, prompt settings, automation, skills, agents, templates, store commands, and generic structured command fallback.
+- Added `golutra-read-cli-guide` so MCP hosts can read the current Golutra CLI team, collaboration, prompt, role, asset, and roadmap guidance directly.
+- Added runtime target fallback for app-backed tools. MCP now tries `stable:desktop`, `stable:server`, `dev:desktop`, then `dev:server` by default, while still allowing explicit `profile`, `hostKind`, or `targetOrder` overrides.
+- Added explicit confirmation fields for destructive or restart operations such as member deletion, conversation deletion, and member restart.
+
+### Changed
+
+- Kept `golutra-cli` as the stable integration boundary and injects `GOLUTRA_CLI_HOST_KIND` only for each spawned CLI child process.
+- Updated documentation, environment examples, generated `dist/`, and tests for the expanded tool surface and runtime selection behavior.
+
+## [0.1.2] - 2026-03-22
+
+### Changed
+
+- Clarified the runtime `workspacePath` contract so per-tool `workspacePath` input is treated as a one-time override, while `golutra-set-context` remains the only way to persist a new default workspace
+- Added regression tests to lock the workspace context behavior at both `ContextStore` level and workspace-aware tool level
+- Expanded README and `STARTUP_PROCESS.md` so AI hosts can understand the recommended runtime flow for diagnostics, workspace switching, and normal tool execution
+- Added `docs/WORKSPACE_CONTEXT_EXAMPLES.md` with concrete examples for stored defaults, one-off workspace overrides, recommended tool order, and a real chat flow
+- Updated the diagnostic examples to explain that a `workspacePath` passed to `golutra-diagnose` affects only that call and does not mutate the stored default context
+
 ## [0.1.1] - 2026-03-21
 
 ### Changed

package/README.md

@@ -1,8 +1,44 @@
-# golutra-mcp
-
-`golutra-mcp` is an MCP bridge project for Golutra.
-
-`golutra-mcp` 是一个面向 Golutra 的 MCP 桥接项目。
+<p align="center">
+  <a href="https://www.golutra.com/" target="_blank" rel="noopener noreferrer">
+    <img
+      width="96"
+      src="./assets/readme/golutra-logo.png"
+      alt="golutra logo"
+    />
+  </a>
+</p>
+
+<h1 align="center">golutra-mcp</h1>
+
+<p align="center">
+  MCP bridge for Golutra via golutra-cli. <br />
+  通过 golutra-cli 暴露 Golutra 能力的 MCP 桥接层。
+</p>
+
+<p align="center">
+  <a href="https://www.npmjs.com/package/golutra-mcp"><img src="https://img.shields.io/npm/v/golutra-mcp?label=npm" alt="npm version"></a>
+  <a href="https://www.npmjs.com/package/golutra-mcp"><img src="https://img.shields.io/npm/dm/golutra-mcp?label=downloads" alt="npm downloads"></a>
+  <a href="https://github.com/golutra/golutra-mcp/actions/workflows/ci.yml"><img src="https://img.shields.io/github/actions/workflow/status/golutra/golutra-mcp/ci.yml?branch=main&label=ci" alt="ci"></a>
+  <a href="https://www.npmjs.com/package/golutra-mcp"><img src="https://img.shields.io/badge/node-%3E%3D20.11-2f7af8" alt="node version"></a>
+  <a href="./LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-ff9f1a" alt="license"></a>
+</p>
+
+<p align="center">
+  <a href="#english">English</a> ·
+  <a href="#中文">中文</a> ·
+  <a href="https://www.npmjs.com/package/golutra-mcp">npm</a> ·
+  <a href="https://github.com/golutra/golutra-mcp">GitHub</a> ·
+  <a href="./STARTUP_PROCESS.md">Startup Process</a> ·
+  <a href="./docs/WORKSPACE_CONTEXT_EXAMPLES.md">Workspace Examples</a> ·
+  <a href="./docs/GOLUTRA_DIAGNOSE_EXAMPLES.md">Diagnose Examples</a>
+</p>
+
+<p align="center">
+  Keep Golutra as the app runtime. Use golutra-cli as the stable boundary. Expose the workflow through MCP. <br />
+  保留 Golutra 作为桌面运行时，以 golutra-cli 作为稳定边界，再通过 MCP 暴露给外部 AI 宿主。
+</p>
+
+---
 
 ## English
 
@@ -49,7 +85,7 @@ golutra-mcp
 
 `golutra-mcp` is a Model Context Protocol server that exposes Golutra collaboration capabilities to MCP-compatible hosts through `golutra-cli`.
 
-It is not a replacement for Golutra itself, and it does not re-implement Golutra's local IPC protocol. Instead, it acts as a thin integration layer that lets external MCP clients reuse Golutra's existing chat, roadmap, and skill flows through a smaller and more stable boundary.
+It is not a replacement for Golutra itself, and it does not re-implement Golutra's local IPC protocol. Instead, it acts as a thin integration layer that lets external MCP clients reuse Golutra's existing team-building, chat, roadmap, prompt, automation, and skill flows through a smaller and more stable boundary.
 
 ### What It Is Today
 
@@ -59,7 +95,7 @@ Today it already provides:
 
 - a local `stdio` MCP server
 - a command bridge based on `golutra-cli`
-- tool coverage for chat, roadmap, context, diagnostics, and skill discovery
+- tool coverage for CLI guides, team config, terminal creation, member deletion, conversation topology, chat, roadmap, prompt settings, member bindings, automation, agents, templates, store commands, context, diagnostics, and skill discovery
 - skill validation and direct project `SKILL.md` reading for local Golutra skill workflows
 - an open-source project skeleton with contribution, security, CI, and release-facing metadata
 
@@ -83,7 +119,7 @@ To work correctly, the server still depends on the existing Golutra desktop runt
 - a locally installed Golutra desktop application
 - a reachable `golutra-cli` binary
 - a valid Golutra workspace path
-- the target Golutra desktop app profile running locally, usually `stable`
+- the target Golutra app runtime running locally. By default MCP tries `stable` desktop, `stable` server/web, `dev` desktop, then `dev` server/web.
 
 Default CLI discovery by platform:
 
@@ -97,12 +133,32 @@ Use `golutra-diagnose` when you need to separate:
 
 - CLI path problems
 - missing or invalid workspace paths
-- missing user identity for app-backed probes
+- workspace team config and app-backed command failures
 - app-not-running or profile-mismatch failures
 - generic app command failures
 
 Detailed diagnostic output fields and common `reasonCode` values are documented in `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`.
 
+### What An AI Host Should Do
+
+If an AI system or MCP-compatible host sees this repository, the intended usage is:
+
+1. Launch `golutra-mcp` as a local `stdio` MCP server, not as an HTTP service.
+2. Provide `GOLUTRA_CLI_PATH` and usually `GOLUTRA_WORKSPACE_PATH`. Leave profile/host unset to use the default target order, or set `GOLUTRA_PROFILE`, `GOLUTRA_CLI_HOST_KIND`, or `GOLUTRA_TARGET_ORDER` when you need a specific runtime.
+3. Call `golutra-get-context` or `golutra-diagnose` first to confirm runtime readiness.
+4. Read the relevant guide before acting, for example `golutra-read-cli-guide` with `guide: "team"` before team creation.
+5. Use the structured team-building flow instead of inventing a custom transport:
+   `golutra-read-team-config` -> `golutra-list-terminal-defaults` / `golutra-create-terminals` / conversation tools / prompt tools / automation tools.
+6. For runtime collaboration after the team exists, use:
+   `golutra-list-conversations` -> `golutra-list-messages` / `golutra-send-message` / `golutra-read-roadmap` / `golutra-update-roadmap`.
+7. Treat `golutra-cli` as the stable boundary. Do not bypass this project by directly calling Golutra local socket IPC unless you intentionally want to maintain a separate integration layer.
+8. For destructive or restart tools, pass the explicit confirmation fields required by the tool schema, such as `confirmedMemberId` or `confirmedConversationId`.
+9. When switching workspaces for a single request, pass `workspacePath` on that tool call. Use `golutra-set-context` only when you want to persist a new default for later calls.
+
+In short: start with diagnostics, read `golutra-read-team-config` for the workspace shape, keep workspace/profile/host explicit when needed, and use the provided MCP tools as the integration contract.
+
+For concrete workspace switching and chat flow examples, see `docs/WORKSPACE_CONTEXT_EXAMPLES.md`.
+
 ### Future Direction
 
 The next stages should move the project from "basic bridge" to "usable integration product."
@@ -175,7 +231,7 @@ golutra-mcp
 
 `golutra-mcp` 是一个把 Golutra 能力暴露给 MCP 客户端的桥接层，底层通过 `golutra-cli` 与 Golutra 桌面端联通。
 
-它不是 Golutra 本体，也不是对 Golutra 本地 IPC 协议的重写。这个仓库的职责，是把外部 MCP Host 和 Golutra 之间的集成边界收敛成一层更小、更稳定、更容易复用的适配层。
+它不是 Golutra 本体，也不是对 Golutra 本地 IPC 协议的重写。这个仓库的职责，是把外部 MCP Host 和 Golutra 之间的集成边界收敛成一层更小、更稳定、更容易复用的适配层，覆盖团队创建、聊天、路线图、提示词、自动化和技能等主要工作流。
 
 ### 当前阶段是什么
 
@@ -185,7 +241,7 @@ golutra-mcp
 
 - 基于 `stdio` 的 MCP Server 形态
 - 基于 `golutra-cli` 的命令桥接
-- chat、roadmap、context、diagnostics、skills 这些基础工具面
+- CLI 指南、team config、terminal 创建、成员删除、频道/私聊拓扑、chat、roadmap、prompt settings、member bindings、automation、agents、templates、store commands、context、diagnostics、skills 等工具面
 - 技能校验与项目 `SKILL.md` 直接读取能力，能覆盖本地技能开发链路
 - 基本完整的开源项目骨架，包括贡献规范、安全策略、CI 和发布元数据
 
@@ -209,7 +265,7 @@ golutra-mcp
 - 本机已安装 Golutra 桌面应用
 - 能访问到 `golutra-cli`
 - 已知的有效工作区路径
-- 本地已启动目标 profile 的 Golutra 桌面应用，通常使用 `stable`
+- 本地已启动目标 Golutra 运行实例。默认查找顺序是 `stable` 桌面端、`stable` server/web、`dev` 桌面端、`dev` server/web。
 
 按平台的默认 CLI 自动发现顺序：
 
@@ -223,12 +279,32 @@ golutra-mcp
 
 - CLI 路径问题
 - workspacePath 缺失或非法
-- userId 缺失导致 app 探针跳过
+- 工作区团队配置读取与 app 侧命令失败
 - 桌面应用未运行或 profile 不匹配
 - 普通 app 命令失败
 
 更完整的诊断输出字段和常见 `reasonCode` 说明见 `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`。
 
+### AI 看到这个项目后应该怎么做
+
+如果一个 AI 系统或支持 MCP 的宿主看到这个仓库，推荐按下面方式接入：
+
+1. 把 `golutra-mcp` 当作本地 `stdio` MCP Server 启动，不要把它当成 HTTP 服务。
+2. 提供 `GOLUTRA_CLI_PATH`，通常还需要提供 `GOLUTRA_WORKSPACE_PATH`。profile/host 不填时使用默认查找顺序；需要固定运行实例时再设置 `GOLUTRA_PROFILE`、`GOLUTRA_CLI_HOST_KIND` 或 `GOLUTRA_TARGET_ORDER`。
+3. 先调用 `golutra-get-context` 或 `golutra-diagnose`，确认运行时上下文和联通状态。
+4. 执行前先读对应指南，例如创建团队前用 `golutra-read-cli-guide` 读取 `guide: "team"`。
+5. 创建团队时按标准工具链路走，不要自造传输协议：
+   `golutra-read-team-config` -> `golutra-list-terminal-defaults` / `golutra-create-terminals` / 会话拓扑工具 / 提示词工具 / 自动化工具。
+6. 团队创建完成后的运行期协作使用：
+   `golutra-list-conversations` -> `golutra-list-messages` / `golutra-send-message` / `golutra-read-roadmap` / `golutra-update-roadmap`。
+7. 把 `golutra-cli` 视为稳定边界。除非你明确准备长期维护另一套集成层，否则不要绕过这个项目去直连 Golutra 本地 socket IPC。
+8. 删除或重启类工具必须按 tool schema 传入显式确认字段，例如 `confirmedMemberId` 或 `confirmedConversationId`。
+9. 如果只是某一次调用切换工作区，就在该次 tool 调用里显式传 `workspacePath`。只有在你希望后续调用默认都改到新工作区时，才使用 `golutra-set-context`。
+
+一句话概括：先诊断，再用 `golutra-read-team-config` 读取工作区形态，必要时显式指定 workspace/profile/host，然后把 README 里提供的 MCP tools 当作正式集成契约来用。
+
+如果你想看“工作区切换”和“真实聊天链路”的具体调用示例，直接看 `docs/WORKSPACE_CONTEXT_EXAMPLES.md`。
+
 ### 后续规划
 
 后续项目应该从“能桥接”继续推进到“更好用、可发布、可维护”。
@@ -260,6 +336,8 @@ npm run dev
 
 - Startup, installation, validation, and MCP client wiring:
   [STARTUP_PROCESS.md](./STARTUP_PROCESS.md)
+- Workspace override and stored default examples:
+  [docs/WORKSPACE_CONTEXT_EXAMPLES.md](./docs/WORKSPACE_CONTEXT_EXAMPLES.md)
 - Diagnostic output examples and reason codes:
   [docs/GOLUTRA_DIAGNOSE_EXAMPLES.md](./docs/GOLUTRA_DIAGNOSE_EXAMPLES.md)
 - Contribution guide:

package/STARTUP_PROCESS.md

@@ -47,6 +47,15 @@ This repository focuses on protocol translation, context management, diagnostics
 - `golutra-diagnose` also returns `summary.status` (`ok`, `partial`, `error`), `reasonCodes`, and `nextSteps`
 - Detailed output examples and common `reasonCode` values live in `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`
 
+### Workspace Override Contract
+
+- Passing `workspacePath` in a tool call is a one-time override for that call only
+- `golutra-set-context` is the explicit operation that persists a new default `workspacePath` for later calls
+- If an AI host switches workspaces frequently, prefer passing `workspacePath` per call instead of mutating shared defaults
+- 如果只是某一次调用临时切换工作区，直接在该次 tool 输入里传 `workspacePath`
+- 如果希望后续调用默认都切到新工作区，再使用 `golutra-set-context`
+- Concrete request sequences are documented in `docs/WORKSPACE_CONTEXT_EXAMPLES.md`
+
 ### Current Limitations
 
 - `workspacePath` must be provided either in the tool call or through `golutra-set-context`
@@ -82,6 +91,10 @@ It still needs more real-world validation across MCP hosts, operating systems, a
   Default: auto-discover a platform-specific `golutra-cli` install when available, otherwise fall back to the platform command name from `PATH`
 - `GOLUTRA_PROFILE`
   Optional Golutra runtime profile: `dev`, `canary`, or `stable`
+- `GOLUTRA_CLI_HOST_KIND`
+  Optional Golutra runtime host: `desktop` or `server`; `web` maps to `server`
+- `GOLUTRA_TARGET_ORDER`
+  Optional comma-separated runtime search order, for example `stable:desktop,stable:server,dev:desktop,dev:server`
 - `GOLUTRA_WORKSPACE_PATH`
   Optional default workspace path used by tools that require a workspace
 - `GOLUTRA_COMMAND_TIMEOUT_MS`
@@ -89,6 +102,13 @@ It still needs more real-world validation across MCP hosts, operating systems, a
 
 Use [.env.example](./.env.example) as the minimal local template.
 
+When profile/host are not pinned, MCP tries runtime targets in this order:
+
+- `stable:desktop`
+- `stable:server` / web
+- `dev:desktop`
+- `dev:server` / web
+
 Default CLI discovery order:
 
 - macOS: `/Applications/Golutra.app/Contents/MacOS/golutra-cli`, `~/Applications/Golutra.app/Contents/MacOS/golutra-cli`, `golutra-cli`
@@ -140,6 +160,46 @@ export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
 golutra-mcp
 ```
 
+## Quick Verification After Install
+
+Use this sequence when you want to confirm that the published package and the local Golutra runtime are wired correctly.
+
+1. Confirm the package is visible from npm:
+
+```bash
+npm view golutra-mcp version
+```
+
+2. Confirm the binary can start with your local Golutra runtime settings:
+
+macOS/Linux:
+
+```bash
+export GOLUTRA_CLI_PATH=/absolute/path/to/golutra-cli
+export GOLUTRA_PROFILE=stable
+export GOLUTRA_WORKSPACE_PATH=/absolute/path/to/workspace
+golutra-mcp
+```
+
+Windows PowerShell:
+
+```powershell
+$env:GOLUTRA_CLI_PATH="C:\absolute\path\to\golutra-cli.exe"
+$env:GOLUTRA_PROFILE="stable"
+$env:GOLUTRA_WORKSPACE_PATH="C:\absolute\path\to\workspace"
+golutra-mcp
+```
+
+3. If your MCP host can call tools immediately, run `golutra-get-context` or `golutra-diagnose`.
+
+What to expect:
+
+- `golutra-get-context` should return the resolved `cliPath`, `profile`, `workspacePath`, and `timeoutMs`
+- `golutra-diagnose` should report `checks.cliPath.ok = true` and `checks.cliCommand.ok = true`
+- If you also provide a valid workspace `userId`, `golutra-diagnose` should attempt the app-backed `chat.conversations.list` probe
+
+If installation succeeds but runtime access still fails, use `golutra-diagnose` first and then compare the output with `docs/GOLUTRA_DIAGNOSE_EXAMPLES.md`.
+
 ## Local Development
 
 Start the MCP server directly from source:
@@ -225,6 +285,43 @@ npm pack --dry-run
 
 `prepack` is configured to build the project before npm packaging.
 
+## Publish To npm
+
+Use this flow for a normal public npm release:
+
+1. Confirm you are in the repository root and that checks pass:
+
+```bash
+cd /path/to/golutra-mcp
+npm run check
+npm pack
+```
+
+2. Confirm your npm CLI session is authenticated:
+
+```bash
+npm whoami
+```
+
+3. Publish the package:
+
+```bash
+npm publish
+```
+
+4. Verify the published result:
+
+```bash
+npm view golutra-mcp version
+npm view golutra-mcp
+```
+
+Release notes:
+
+- If `npm publish` reports that the version already exists, bump `package.json` to the next version and publish again
+- If npm requires browser or OTP confirmation, complete that flow and wait for the CLI to print `+ golutra-mcp@<version>`
+- `npm pack` creates a local `.tgz` artifact in the repository root; this is useful for pre-publish inspection or private file distribution
+
 ## Self-Hosted E2E CI
 
 The repository includes a dedicated GitHub Actions workflow for real MCP smoke tests on a macOS self-hosted runner:

package/dist/lib/cli-runner.d.ts

@@ -1,7 +1,10 @@
 import type { CliCommandRequest } from "./types.js";
 export interface CliJsonRunner {
     executeJson<T>(request: CliCommandRequest): Promise<T>;
+    executeText?(request: CliCommandRequest): Promise<string>;
 }
 export declare class NodeCliJsonRunner implements CliJsonRunner {
+    private executeRaw;
+    executeText(request: CliCommandRequest): Promise<string>;
     executeJson<T>(request: CliCommandRequest): Promise<T>;
 }

package/dist/lib/cli-runner.js

@@ -20,18 +20,21 @@ function extractErrorMessage(parsed) {
     return undefined;
 }
 export class NodeCliJsonRunner {
-    async executeJson(request) {
+    async executeRaw(request) {
         const stdoutChunks = [];
         const stderrChunks = [];
         const child = spawn(request.cliPath, request.args, {
-            env: process.env,
+            env: {
+                ...process.env,
+                ...request.env
+            },
             stdio: ["ignore", "pipe", "pipe"]
         });
         child.stdout.setEncoding("utf8");
         child.stderr.setEncoding("utf8");
         child.stdout.on("data", (chunk) => stdoutChunks.push(chunk));
         child.stderr.on("data", (chunk) => stderrChunks.push(chunk));
-        const completed = await new Promise((resolve, reject) => {
+        return new Promise((resolve, reject) => {
             const timer = setTimeout(() => {
                 child.kill("SIGTERM");
                 reject(new CliExecutionError({
@@ -63,6 +66,25 @@ export class NodeCliJsonRunner {
                 });
             });
         });
+    }
+    async executeText(request) {
+        const completed = await this.executeRaw(request);
+        if (completed.exitCode !== 0) {
+            throw new CliExecutionError({
+                message: completed.stderr.trim() ||
+                    completed.stdout.trim() ||
+                    `golutra-cli exited with code ${completed.exitCode}`,
+                cliPath: request.cliPath,
+                args: request.args,
+                exitCode: completed.exitCode,
+                stdout: completed.stdout,
+                stderr: completed.stderr
+            });
+        }
+        return completed.stdout.trimEnd();
+    }
+    async executeJson(request) {
+        const completed = await this.executeRaw(request);
         const trimmedStdout = completed.stdout.trim();
         if (!trimmedStdout) {
             throw new CliExecutionError({

package/dist/lib/cli-runner.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli-runner.js","sourceRoot":"","sources":["../../src/lib/cli-runner.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli-runner.js","sourceRoot":"","sources":["../../src/lib/cli-runner.ts"],"names":[],"mappings":"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"}

package/dist/lib/context.d.ts

@@ -1,4 +1,6 @@
-import type { CommandContextInput, RuntimeContextSnapshot } from "./types.js";
+import type { CommandContextInput, GolutraRuntimeTarget, RuntimeContextSnapshot } from "./types.js";
+export declare const DEFAULT_TARGET_ORDER: GolutraRuntimeTarget[];
+export declare function resolveRuntimeTargets(context: RuntimeContextSnapshot): GolutraRuntimeTarget[];
 export declare function resolveDefaultCliPath(env: NodeJS.ProcessEnv, options?: {
     platform?: NodeJS.Platform;
     homeDirectory?: string;
@@ -11,6 +13,7 @@ export declare class ContextStore {
     constructor(initialContext: RuntimeContextSnapshot);
     getSnapshot(): RuntimeContextSnapshot;
     reset(): RuntimeContextSnapshot;
+    private mergeContext;
     update(nextValues: CommandContextInput): RuntimeContextSnapshot;
     resolveCommandContext(nextValues?: CommandContextInput): RuntimeContextSnapshot;
     requireWorkspacePath(nextValues?: CommandContextInput): string;

package/dist/lib/context.js

@@ -1,9 +1,15 @@
 import { existsSync } from "node:fs";
 import { homedir } from "node:os";
 import path from "node:path";
-import { GOLUTRA_PROFILES } from "./types.js";
+import { GOLUTRA_HOST_KINDS, GOLUTRA_PROFILES } from "./types.js";
 const DEFAULT_TIMEOUT_MS = 30_000;
 const MAX_TIMEOUT_MS = 300_000;
+export const DEFAULT_TARGET_ORDER = [
+    { profile: "stable", hostKind: "desktop" },
+    { profile: "stable", hostKind: "server" },
+    { profile: "dev", hostKind: "desktop" },
+    { profile: "dev", hostKind: "server" }
+];
 function normalizeNonEmptyString(value) {
     const trimmed = value?.trim();
     return trimmed ? trimmed : undefined;
@@ -43,6 +49,72 @@ function normalizeProfile(value) {
     }
     throw new Error(`Unsupported Golutra profile: ${trimmed}`);
 }
+function normalizeHostKind(value) {
+    const trimmed = normalizeNonEmptyString(value)?.toLowerCase();
+    if (!trimmed || trimmed === "auto") {
+        return undefined;
+    }
+    const normalized = trimmed === "web" ? "server" : trimmed;
+    if (GOLUTRA_HOST_KINDS.includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Unsupported Golutra hostKind: ${trimmed}`);
+}
+function normalizeTargetOrder(value) {
+    if (Array.isArray(value)) {
+        const targets = value.map((target) => ({
+            profile: normalizeProfile(target.profile) ?? "stable",
+            hostKind: normalizeHostKind(target.hostKind) ?? "desktop"
+        }));
+        return targets.length > 0 ? dedupeTargets(targets) : undefined;
+    }
+    const trimmed = normalizeNonEmptyString(value);
+    if (!trimmed) {
+        return undefined;
+    }
+    const targets = trimmed.split(",").map((rawTarget) => {
+        const [rawProfile, rawHostKind] = rawTarget.split(":");
+        const profile = normalizeProfile(rawProfile);
+        const hostKind = normalizeHostKind(rawHostKind);
+        if (!profile || !hostKind) {
+            throw new Error("Unsupported Golutra targetOrder entry. Expected profile:hostKind, for example stable:desktop.");
+        }
+        return { profile, hostKind };
+    });
+    return targets.length > 0 ? dedupeTargets(targets) : undefined;
+}
+function dedupeTargets(targets) {
+    const seen = new Set();
+    const result = [];
+    for (const target of targets) {
+        const key = `${target.profile}:${target.hostKind}`;
+        if (seen.has(key)) {
+            continue;
+        }
+        seen.add(key);
+        result.push(target);
+    }
+    return result;
+}
+export function resolveRuntimeTargets(context) {
+    if (context.targetOrder && context.targetOrder.length > 0) {
+        return context.targetOrder;
+    }
+    const profiles = context.profile
+        ? [context.profile]
+        : DEFAULT_TARGET_ORDER.map((target) => target.profile);
+    const hostKinds = context.hostKind
+        ? [context.hostKind]
+        : DEFAULT_TARGET_ORDER.map((target) => target.hostKind);
+    const candidates = [];
+    for (const defaultTarget of DEFAULT_TARGET_ORDER) {
+        if (profiles.includes(defaultTarget.profile) &&
+            hostKinds.includes(defaultTarget.hostKind)) {
+            candidates.push(defaultTarget);
+        }
+    }
+    return dedupeTargets(candidates);
+}
 function getDefaultCliCommand(platform) {
     return platform === "win32" ? "golutra-cli.exe" : "golutra-cli";
 }
@@ -101,12 +173,27 @@ export function resolveDefaultCliPath(env, options = {}) {
     return (candidates.find((candidatePath) => pathModule.isAbsolute(candidatePath) && pathExists(candidatePath)) ?? fallbackCommand);
 }
 export function createInitialContext(env) {
-    return {
+    const context = {
         cliPath: resolveDefaultCliPath(env),
-        profile: normalizeProfile(env.GOLUTRA_PROFILE),
-        workspacePath: normalizeNonEmptyString(env.GOLUTRA_WORKSPACE_PATH),
         timeoutMs: normalizeTimeout(env.GOLUTRA_COMMAND_TIMEOUT_MS)
     };
+    const profile = normalizeProfile(env.GOLUTRA_PROFILE);
+    const hostKind = normalizeHostKind(env.GOLUTRA_CLI_HOST_KIND ?? env.GOLUTRA_HOST_KIND);
+    const targetOrder = normalizeTargetOrder(env.GOLUTRA_TARGET_ORDER);
+    const workspacePath = normalizeNonEmptyString(env.GOLUTRA_WORKSPACE_PATH);
+    if (profile) {
+        context.profile = profile;
+    }
+    if (hostKind) {
+        context.hostKind = hostKind;
+    }
+    if (targetOrder) {
+        context.targetOrder = targetOrder;
+    }
+    if (workspacePath) {
+        context.workspacePath = workspacePath;
+    }
+    return context;
 }
 export class ContextStore {
     initialContext;
@@ -122,29 +209,45 @@ export class ContextStore {
         this.context = { ...this.initialContext };
         return this.getSnapshot();
     }
-    update(nextValues) {
+    mergeContext(baseContext, nextValues) {
         const nextContext = {
-            cliPath: normalizeNonEmptyString(nextValues.cliPath) ?? this.context.cliPath,
-            profile: nextValues.profile ?? this.context.profile,
-            workspacePath: normalizeNonEmptyString(nextValues.workspacePath) ??
-                this.context.workspacePath,
+            cliPath: normalizeNonEmptyString(nextValues.cliPath) ?? baseContext.cliPath,
             timeoutMs: typeof nextValues.timeoutMs === "number"
                 ? normalizeTimeout(nextValues.timeoutMs)
-                : this.context.timeoutMs
+                : baseContext.timeoutMs
         };
+        const profile = nextValues.profile ?? baseContext.profile;
+        const hostKind = nextValues.hostKind ?? baseContext.hostKind;
+        const targetOrder = nextValues.targetOrder !== undefined
+            ? normalizeTargetOrder(nextValues.targetOrder)
+            : nextValues.profile !== undefined || nextValues.hostKind !== undefined
+                ? undefined
+                : baseContext.targetOrder;
+        const workspacePath = normalizeNonEmptyString(nextValues.workspacePath) ??
+            baseContext.workspacePath;
+        if (profile) {
+            nextContext.profile = profile;
+        }
+        if (hostKind) {
+            nextContext.hostKind = hostKind;
+        }
+        if (targetOrder) {
+            nextContext.targetOrder = targetOrder;
+        }
+        if (workspacePath) {
+            nextContext.workspacePath = workspacePath;
+        }
+        return nextContext;
+    }
+    update(nextValues) {
+        // `golutra-set-context` 走这里，表示显式持久化更新默认上下文。
+        const nextContext = this.mergeContext(this.context, nextValues);
         this.context = nextContext;
         return this.getSnapshot();
     }
     resolveCommandContext(nextValues = {}) {
-        return {
-            cliPath: normalizeNonEmptyString(nextValues.cliPath) ?? this.context.cliPath,
-            profile: nextValues.profile ?? this.context.profile,
-            workspacePath: normalizeNonEmptyString(nextValues.workspacePath) ??
-                this.context.workspacePath,
-            timeoutMs: typeof nextValues.timeoutMs === "number"
-                ? normalizeTimeout(nextValues.timeoutMs)
-                : this.context.timeoutMs
-        };
+        // 普通业务 tool 走这里时，`workspacePath` 只是本次调用覆盖，不会写回默认缓存。
+        return this.mergeContext(this.context, nextValues);
     }
     requireWorkspacePath(nextValues = {}) {
         const workspacePath = this.resolveCommandContext(nextValues).workspacePath;