IDE Subsystem & Workspace Management

IDE Subsystem & Workspace Management

The IDE subsystem (kazma_core/ide/) is a transport-agnostic coding backend supporting Web UI, TUI, CLI, and cross-platform chat bots (Telegram, Discord, Slack). It serves as the single source of truth for file operations, execution, git management, and workspace resolution.

---

1. Workspace Resolution Precedence

Workspace root paths are resolved dynamically with strict precedence to prevent out-of-boundary access:

1. ContextVar Scope: workspace_scope per async task context.
2. Global Active Workspace: Configured via configure_workspace().
3. Environment Variable: KAZMA_WORKSPACE.
4. Active WorkspaceStore Row: Active path in workspaces.db.
5. Default Fallback: cwd/kazma-data/workspace.

Path-traversal attacks are blocked using string-level normalization and realpath containment checks.

Path grants (outside-workspace access)

Access outside the active workspace is denied by default, but can be opened with permission. Source of truth: kazma_core/workspace/path_policy.py + workspace/path_grants.py, wired through IdeService.resolve, file_read / file_write, file list/search/delete/append, and the shell path checks.

How	Effect
Chat (smooth)	When a file tool fails on an outside-workspace path, the agent calls request_path_access (a danger-tier HITL card). On approval a session grant (~1h TTL) is created and the tool retries.
Settings / API	Durable extra roots via workspace.extra_roots + GET/PUT /api/workspace/extra_roots (path, mode: read | write, label). Persist until removed.

Read grants never allow writes. Denial messages tell the agent how to request a grant, so the loop is smooth rather than a hard failure.

---

2. Per-Task Workspace Targeting

Concurrent swarm tasks or user turns can target different repositories simultaneously using workspace_scope(workspace_id).

from kazma_core.ide.workspace_scope import workspace_scope

async with workspace_scope(workspace_id="repo-b"):
    # File tools automatically target repo-b root
    await file_write("src/index.py", content)

---

3. Awareness Injection (env_context.py)

At the start of every turn, build_env_context() generates a markdown metadata block detailing:

• Workspace root absolute path
• Repo identity (GitHub owner/repo)
• Current git branch & remote
• Available tool capabilities

This awareness block is injected into the supervisor prompt, per-turn SSE chat stream, and every dispatched swarm worker context.