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() keeps its cwd project/workspace scoped: cwd must be a relative path under the project root. The host does not implicitly resolve command or args against the plugin package. Use the absolute ctx.pluginRoot supplied at activation time to construct an explicit path to a packaged script, and pass that path as command or as an argument to its interpreter. Treat package files as read-only.

const script = `${ctx.pluginRoot.replace(/[\\/]+$/, "")}/scripts/check.mjs`;
await ctx.services.tasks.runCommand({
  projectId,
  ownerAgentId,
  label: "Run packaged check",
  command: "node",
  args: [script],
  cwd: "."
});

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.

2.5 KiB Raw Blame History