Skip to content

workflow_shell_working_directory.md

Latest commit

 

History

History
123 lines (82 loc) · 4.49 KB

workflow_shell_working_directory.md

File metadata and controls

123 lines (82 loc) · 4.49 KB
Raw

Workflow Shell Working Directory

Overview

When a workflow execution agent runs execute_shell_command, the working directory it defaults to is determined by a session-scoped config map. This doc explains how that plumbing works and where the working directory is set at each stage.

Two Session IDs

There are two distinct session IDs in the system:

ID Created Stored
HTTP session ID From X-Session-ID request header sessionID in server.go
MCP session ID workflow-session-{timestamp} in workflow_orchestrator.go hcpo.sessionID

The session working dir config map (common.sessionShellConfigs) is keyed by the HTTP session ID.

How Session Working Dir Is Looked Up

execute_shell_command.go reads ChatSessionIDKey from context to find the session:

ctx → ChatSessionIDKey → sessionID → GetSessionShellConfig(sessionID) → WorkingDir

Priority order when no explicit working_directory arg is passed:

  1. sessionCfg.WorkingDir (session map, keyed by ChatSessionIDKey in context)
  2. c.DefaultWorkingDir (workspace client field — typically empty)
  3. c.ExtraEnv["_DEFAULT_WORKING_DIR"]
  4. Empty → workspace root

workflowCtx Setup (server.go)

The workflow execution runs in a fresh context (context.Background()):

workflowCtx = context.WithCancel(context.Background())
workflowCtx = context.WithValue(workflowCtx, common.UserIDKey, currentUserID)
workflowCtx = context.WithValue(workflowCtx, common.ChatSessionIDKey, sessionID)  // injects HTTP session ID

The ChatSessionIDKey injection (third line) is critical — without it, all execution agent shell commands would fall through to workspace root as the working directory, ignoring whatever was set via SetSessionWorkingDir.

Note: The main chat agent also injects ChatSessionIDKey at server.go:5138 into its own agentCtx. Phase chat agents use this same path.

Working Directory Lifecycle During Execution

On workflow start (server.go:2771)

workspace.SetSessionWorkingDir(sessionID, workflowWorkspacePath)
// e.g. "Workflow/HRMS"

All shell commands at this point default to Workflow/HRMS.

On run folder selection (controller.go / execution_manager.go)

When a run folder is resolved (either from frontend options or interactive selection), the session working dir is updated to the run's execution folder:

// controller.go (frontend path, line ~549)
common.SetSessionWorkingDir(hcpo.httpSessionID, "Workflow/HRMS/runs/run-001/execution")

// controller.go (interactive path, line ~605)
common.SetSessionWorkingDir(hcpo.httpSessionID, "Workflow/HRMS/runs/run-001/execution")

// execution_manager.go (batch execution path, applyExecutionContext)
common.SetSessionWorkingDir(orch.httpSessionID, "Workflow/HRMS/runs/run-001/execution")

After this point, all shell commands (execution agents, learning agents, and todo-task agents) default to Workflow/HRMS/runs/run-001/execution.

Folder Guard vs Working Directory

These are separate mechanisms:

  • Working directory: where relative paths and ./ resolve for shell commands
  • Folder guard: which paths an agent is allowed to read/write (enforced via Isolator)

The folder guard for execution agents is set per-step via SetWorkspacePathForFolderGuard (snapshotted at agent creation time in WrapWorkspaceToolsWithFolderGuard). It is narrower than the working directory — e.g., write access restricted to execution/step-3/.

The working directory is broader — the whole execution/ folder — so the agent can read previous step outputs with relative paths like ../step-2/output.json.

Workshop Builder Phase

The interactive workshop (workflow builder) also runs in workflowCtx and inherits the ChatSessionIDKey. At build time, selectedRunFolder is not yet set, so the working directory remains Workflow/HRMS — correct for a builder that reads/writes planning files.

Summary Table

Stage Working Dir How set
Workflow start Workflow/HRMS SetSessionWorkingDir in server.go:2771
After run folder selected Workflow/HRMS/runs/run-001/execution common.SetSessionWorkingDir in controller.go / execution_manager.go
Chat agent Chats/ DefaultWorkingDirKey context injection in tool_setup.go
Phase chat agent phaseWorkspacePath SetSessionWorkingDir in server.go:4472
Plans agent Chats/ SetSessionWorkingDir in server.go:3756