76 lines
2.3 KiB
Markdown
76 lines
2.3 KiB
Markdown
# Services
|
|
|
|
`ctx.services` is the stable public host facade. It is available to plugins that
|
|
declare `ui` or `tooling` capabilities.
|
|
|
|
```json
|
|
{
|
|
"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](windows.md).
|