@kdlbs/plugin-sdk 0.0.0-stage → 0.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +661 -0
- package/README.md +68 -2
- package/package.json +32 -4
- package/sdk-release.json +11 -0
- package/src/index.ts +1522 -0
package/README.md
CHANGED
|
@@ -1,3 +1,69 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kdlbs/plugin-sdk
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Runtime-free TypeScript contracts for Kandev UI plugins.
|
|
4
|
+
|
|
5
|
+
The shared Go/npm SDK version starts at `0.1.0`, independently of Kandev.
|
|
6
|
+
Public installation is available only after a verified Stable SDK release.
|
|
7
|
+
After that release, install an exact version with
|
|
8
|
+
`npm install --save-dev --save-exact @kdlbs/plugin-sdk@0.1.0` and commit the
|
|
9
|
+
lockfile. Read the exported `@kdlbs/plugin-sdk/sdk-release.json` for the
|
|
10
|
+
originating host, SDK-wide host floor, and supported manifest API versions.
|
|
11
|
+
|
|
12
|
+
Run the Go-hosted compatibility command from the frontend project root:
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
go run github.com/kdlbs/kandev/pluginsdk/cmd/kandev-sdk-check@v0.1.0 \
|
|
16
|
+
--manifest manifest.yaml --frontend-only --frontend-sdk node_modules/@kdlbs/plugin-sdk
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
The checker supports npm lockfile v2/v3 and pnpm lockfile v9. It rejects local
|
|
20
|
+
SDK links and insufficient host minima. See the
|
|
21
|
+
[authoring guide](https://github.com/kdlbs/kandev/blob/main/docs/public/plugins-authoring.md)
|
|
22
|
+
for combined Go/frontend checks and migration. The package is licensed under
|
|
23
|
+
AGPL-3.0-only; see `LICENSE`.
|
|
24
|
+
|
|
25
|
+
Use `import type` from this package and render with the `host.React`, `host.jsx`,
|
|
26
|
+
and `host.ui` values supplied to `initialize`. The package deliberately has no
|
|
27
|
+
dependency on React and no Zustand or Kandev web-application imports, so an
|
|
28
|
+
external plugin can typecheck from an isolated or sparse checkout without
|
|
29
|
+
inheriting the host's private module graph.
|
|
30
|
+
|
|
31
|
+
Official plugins use `host.context` for typed provider-neutral reads. Do not
|
|
32
|
+
copy `AppState` slice shapes or import files from `apps/web`; extend this package
|
|
33
|
+
and the host context implementation when a reusable capability is missing.
|
|
34
|
+
|
|
35
|
+
The `PluginHostV2*` interfaces describe capability and command data that a
|
|
36
|
+
plugin backend may project into its own UI. They are data types only. Browser
|
|
37
|
+
plugins do not receive the privileged Go Host connection or call backend Host
|
|
38
|
+
RPCs directly. Managed conversation input contracts include durable receipts,
|
|
39
|
+
bounded sequence-cursor reads, exact cancellation, and immediate dispatch
|
|
40
|
+
outcomes. A `busy` immediate-dispatch result never means that the host queued
|
|
41
|
+
the input; use enqueue when the caller needs durable delivery while a turn is
|
|
42
|
+
running. Only periodic inputs may request coalescing with a non-empty key.
|
|
43
|
+
|
|
44
|
+
`PluginHostV2TaskCompletionGateSnapshot` is a bounded projection type for a
|
|
45
|
+
plugin UI. Only the Go Host SDK can call the privileged exact completion
|
|
46
|
+
commands; browser plugins cannot set criteria or evidence directly.
|
|
47
|
+
|
|
48
|
+
The web Host SDK also exposes reusable `WorkspaceAgentChat`,
|
|
49
|
+
`WorkspaceTaskStatus`, and `WorkspaceTaskUsage` components, plus typed
|
|
50
|
+
`host.queries` and `host.interactions` facades. Managed-session recovery is
|
|
51
|
+
available only when the Host reports both the session resource version and the
|
|
52
|
+
opaque execution generation; plugins must pass those observed fences back to
|
|
53
|
+
the exact command and must not infer a recovery target from task state alone.
|
|
54
|
+
|
|
55
|
+
Register an English translation catalog with `registry.registerTranslations`
|
|
56
|
+
and render user-facing copy through `host.i18n`. The host scopes catalogs to the
|
|
57
|
+
plugin, supplies locale fallback and plural interpolation, and removes them with
|
|
58
|
+
the plugin generation.
|
|
59
|
+
|
|
60
|
+
Registration `icon` fields accept a curated host icon name or a plugin-owned
|
|
61
|
+
component. Build custom brand glyphs with `host.jsx`; Kandev renders that component
|
|
62
|
+
through its React runtime on navigation, repository, task-link, settings, and review
|
|
63
|
+
surfaces. This keeps provider assets in the provider repository.
|
|
64
|
+
|
|
65
|
+
Composer slot consumers can import `PluginComposerSlotProps` and the
|
|
66
|
+
`PluginTaskCreatedHandler` types. `registerTaskCreatedHandler` is available only
|
|
67
|
+
on create-mode `task-create-input-actions`; its returned disposer unregisters
|
|
68
|
+
the callback. Task-created callbacks may return a promise and receive a readonly
|
|
69
|
+
`{ id, workspace_id }` identity.
|
package/package.json
CHANGED
|
@@ -1,6 +1,34 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kdlbs/plugin-sdk",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.2.0",
|
|
4
|
+
"description": "Versioned frontend contracts for Kandev runtime plugins",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"main": "./src/index.ts",
|
|
7
|
+
"types": "./src/index.ts",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": "./src/index.ts",
|
|
10
|
+
"./sdk-release.json": "./sdk-release.json"
|
|
11
|
+
},
|
|
12
|
+
"files": [
|
|
13
|
+
"src",
|
|
14
|
+
"sdk-release.json",
|
|
15
|
+
"README.md",
|
|
16
|
+
"LICENSE"
|
|
17
|
+
],
|
|
18
|
+
"publishConfig": {
|
|
19
|
+
"access": "public"
|
|
20
|
+
},
|
|
21
|
+
"scripts": {
|
|
22
|
+
"test": "node --test test/*.node.mjs",
|
|
23
|
+
"typecheck": "tsc --noEmit"
|
|
24
|
+
},
|
|
25
|
+
"devDependencies": {
|
|
26
|
+
"typescript": "^5.7.2"
|
|
27
|
+
},
|
|
28
|
+
"license": "AGPL-3.0-only",
|
|
29
|
+
"repository": {
|
|
30
|
+
"type": "git",
|
|
31
|
+
"url": "git+https://github.com/kdlbs/kandev.git",
|
|
32
|
+
"directory": "apps/packages/plugin-sdk"
|
|
33
|
+
}
|
|
34
|
+
}
|