2.3 KiB
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.
runCommand() is project/workspace scoped. Its cwd option is a relative path
under the project root, and command/args are not resolved against the
calling plugin's package. The SDK does not currently provide a public
pluginRoot or package-path resolver for runtime command handlers. Packaged
scripts cannot be launched through runCommand() by referring to their
package-relative path.
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.