IdeaSDK/docs/services.md

Services

ctx.services is the stable public host facade. It is available to plugins that declare ui or tooling capabilities.

{
  "capabilities": ["ui", "tooling"]
}

Workspace

services.workspace reads the focused/current project, project context and project-owned files. Paths are relative to the project root; hosts reject absolute paths and traversal outside the workspace.

Key APIs:

• getCurrentProject()
• getProjectRoot(projectId?)
• readProjectContext(projectId?)
• updateProjectContext(content, projectId?)
• readTextFile(path, projectId?)
• writeTextFile(path, content, projectId?)
• readBinaryFile(path, projectId?)
• writeBinaryFile(path, bytes, projectId?)
• listDirectory(path?, projectId?)
• stat(path, projectId?)
• watch(path, handler, projectId?)
• queryStructure(query?)

Tasks

services.tasks launches and inspects host-managed command tasks.

Use runCommand() only after preconditions are satisfied. ownerAgentId must be a real agent id when work belongs to an agent workflow.

Tooling

services.tooling.diagnose() checks executables, environment values and files from the host-controlled runtime.

Events

services.events.subscribe() provides best-effort bounded subscriptions to public plugin events such as workspace file changes and background task changes. Dispose subscriptions when no longer needed.

Config

services.config reads and updates structured JSON documents in project-owned locations. Use it for configuration the user expects to review/version.

Terminal

services.terminal opens, reattaches and closes terminal sessions:

• open({ cwd?, rows?, cols?, onData? })
• reattach(sessionId, { onData? })
• close(sessionId)

Windows

services.windows.open({ layoutType, state? }) opens a detached OS window for one of the calling plugin's declared layout contributions. See Windows.