@theway-ai/plugin-sdk 0.1.1

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/README.md ADDED
@@ -0,0 +1,50 @@
1
+ # @theway-ai/plugin-sdk
2
+
3
+ TypeScript authoring SDK for theway runtime extensions. It supplies the single public host API, checked-in JSON Schemas, and the same `defineExtension` descriptor used by the daemon's isolated QuickJS host. The host and SDK expose no ABI version selector.
4
+
5
+ ## Install
6
+
7
+ ```sh
8
+ npm install --save-dev @theway-ai/plugin-sdk
9
+ ```
10
+
11
+ ## Create an extension
12
+
13
+ ```ts
14
+ import { defineExtension } from '@theway-ai/plugin-sdk';
15
+
16
+ export default defineExtension((api) => {
17
+ api.on('input', ({ payload }) => ({
18
+ actions: [{
19
+ kind: 'replace_input',
20
+ payload: { message: payload.message },
21
+ }],
22
+ }));
23
+ });
24
+ ```
25
+
26
+ Compile the entry as an ES module and leave `@theway-ai/plugin-sdk` external. The daemon resolves that specifier to its virtual capability-brokered host module. Extension packages do not ship `node_modules` and cannot access Node globals through this SDK.
27
+
28
+ A package manifest points to the compiled entry:
29
+
30
+ ```json
31
+ {
32
+ "id": "example-extension",
33
+ "version": "1.0.0",
34
+ "entry": "dist/index.js",
35
+ "scope": "session",
36
+ "permissions": []
37
+ }
38
+ ```
39
+
40
+ The complete lifecycle, permission, registration, state, and reload contract is documented in [`docs/extensions.md`](../../docs/extensions.md). Raw ABI declarations and JSON Schemas are shipped under [`abi`](abi).
41
+
42
+ ## Validate
43
+
44
+ From the repository root:
45
+
46
+ ```sh
47
+ make plugin-sdk-check
48
+ ```
49
+
50
+ The check builds declarations, typechecks [`examples/basic-extension.ts`](examples/basic-extension.ts), and runs the runtime descriptor tests.
@@ -0,0 +1,137 @@
1
+ {
2
+ "$defs": {
3
+ "ExtensionAction": {
4
+ "additionalProperties": false,
5
+ "properties": {
6
+ "kind": {
7
+ "$ref": "#/$defs/ExtensionActionKind"
8
+ },
9
+ "payload": true
10
+ },
11
+ "required": [
12
+ "kind",
13
+ "payload"
14
+ ],
15
+ "type": "object"
16
+ },
17
+ "ExtensionActionKind": {
18
+ "description": "Stable action categories. Complex payloads stay JSON-compatible at the ABI\nboundary and are decoded into domain-specific DTOs before application.",
19
+ "enum": [
20
+ "replace_input",
21
+ "patch_run_context",
22
+ "replace_context",
23
+ "replace_model_request",
24
+ "replace_provider_headers",
25
+ "replace_provider_payload",
26
+ "replace_message",
27
+ "replace_tool_result",
28
+ "set_state",
29
+ "delete_state",
30
+ "append_custom_event",
31
+ "append_model_context",
32
+ "emit_command_outcome",
33
+ "enqueue_follow_up",
34
+ "emit_diagnostic",
35
+ "register_effect",
36
+ "dispose_effect"
37
+ ],
38
+ "type": "string"
39
+ },
40
+ "ExtensionGateDecision": {
41
+ "oneOf": [
42
+ {
43
+ "additionalProperties": false,
44
+ "properties": {
45
+ "decision": {
46
+ "const": "abstain",
47
+ "type": "string"
48
+ }
49
+ },
50
+ "required": [
51
+ "decision"
52
+ ],
53
+ "type": "object"
54
+ },
55
+ {
56
+ "additionalProperties": false,
57
+ "properties": {
58
+ "decision": {
59
+ "const": "allow",
60
+ "type": "string"
61
+ }
62
+ },
63
+ "required": [
64
+ "decision"
65
+ ],
66
+ "type": "object"
67
+ },
68
+ {
69
+ "additionalProperties": false,
70
+ "properties": {
71
+ "code": {
72
+ "type": "string"
73
+ },
74
+ "decision": {
75
+ "const": "deny",
76
+ "type": "string"
77
+ },
78
+ "message": {
79
+ "type": "string"
80
+ }
81
+ },
82
+ "required": [
83
+ "decision",
84
+ "code",
85
+ "message"
86
+ ],
87
+ "type": "object"
88
+ },
89
+ {
90
+ "additionalProperties": false,
91
+ "properties": {
92
+ "code": {
93
+ "type": "string"
94
+ },
95
+ "decision": {
96
+ "const": "cancel",
97
+ "type": "string"
98
+ },
99
+ "message": {
100
+ "type": "string"
101
+ }
102
+ },
103
+ "required": [
104
+ "decision",
105
+ "code",
106
+ "message"
107
+ ],
108
+ "type": "object"
109
+ }
110
+ ]
111
+ }
112
+ },
113
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
114
+ "additionalProperties": false,
115
+ "description": "Complete return value from one hook invocation.",
116
+ "properties": {
117
+ "actions": {
118
+ "default": [],
119
+ "items": {
120
+ "$ref": "#/$defs/ExtensionAction"
121
+ },
122
+ "type": "array"
123
+ },
124
+ "decision": {
125
+ "anyOf": [
126
+ {
127
+ "$ref": "#/$defs/ExtensionGateDecision"
128
+ },
129
+ {
130
+ "type": "null"
131
+ }
132
+ ]
133
+ }
134
+ },
135
+ "title": "ExtensionActionBatch",
136
+ "type": "object"
137
+ }
@@ -0,0 +1,129 @@
1
+ {
2
+ "$defs": {
3
+ "ExtensionCatalogStatus": {
4
+ "enum": [
5
+ "effective",
6
+ "shadowed",
7
+ "rejected",
8
+ "blocked",
9
+ "disabled",
10
+ "faulted"
11
+ ],
12
+ "type": "string"
13
+ },
14
+ "ExtensionDiagnosticCode": {
15
+ "enum": [
16
+ "manifest_invalid",
17
+ "shadowed",
18
+ "trust_required",
19
+ "permission_denied",
20
+ "load_failed",
21
+ "hook_failed",
22
+ "hook_timed_out",
23
+ "cancelled",
24
+ "resource_limit",
25
+ "circuit_opened",
26
+ "unloaded",
27
+ "reload_pending",
28
+ "state_migration_failed",
29
+ "persistence_failed",
30
+ "queue_overflow",
31
+ "lifecycle_status",
32
+ "contract_violation"
33
+ ],
34
+ "type": "string"
35
+ },
36
+ "ExtensionPermission": {
37
+ "oneOf": [
38
+ {
39
+ "enum": [
40
+ "session.write",
41
+ "tools.register",
42
+ "tools.override",
43
+ "commands.register",
44
+ "providers.register",
45
+ "client.contribute",
46
+ "workspace.read",
47
+ "workspace.write",
48
+ "process.spawn",
49
+ "network.connect",
50
+ "provider.raw"
51
+ ]
52
+ },
53
+ {
54
+ "pattern": "^secrets\\.read:[A-Za-z0-9](?:[A-Za-z0-9._-]{0,126}[A-Za-z0-9])?$",
55
+ "type": "string"
56
+ }
57
+ ]
58
+ },
59
+ "ExtensionScope": {
60
+ "description": "Lifetime boundary for extension instances and their owned effects.",
61
+ "enum": [
62
+ "process",
63
+ "session",
64
+ "run",
65
+ "request"
66
+ ],
67
+ "type": "string"
68
+ },
69
+ "ExtensionSourceLayer": {
70
+ "description": "Discovery layer attached by the host after reading a package manifest.",
71
+ "enum": [
72
+ "global",
73
+ "project"
74
+ ],
75
+ "type": "string"
76
+ }
77
+ },
78
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
79
+ "additionalProperties": false,
80
+ "description": "Client-neutral catalog record. It intentionally omits executable engine\nvalues and secret-bearing provider configuration.",
81
+ "properties": {
82
+ "extensionId": {
83
+ "type": "string"
84
+ },
85
+ "permissions": {
86
+ "default": [],
87
+ "items": {
88
+ "$ref": "#/$defs/ExtensionPermission"
89
+ },
90
+ "type": "array"
91
+ },
92
+ "priority": {
93
+ "format": "int32",
94
+ "type": "integer"
95
+ },
96
+ "reasonCode": {
97
+ "anyOf": [
98
+ {
99
+ "$ref": "#/$defs/ExtensionDiagnosticCode"
100
+ },
101
+ {
102
+ "type": "null"
103
+ }
104
+ ]
105
+ },
106
+ "scope": {
107
+ "$ref": "#/$defs/ExtensionScope"
108
+ },
109
+ "source": {
110
+ "$ref": "#/$defs/ExtensionSourceLayer"
111
+ },
112
+ "status": {
113
+ "$ref": "#/$defs/ExtensionCatalogStatus"
114
+ },
115
+ "version": {
116
+ "type": "string"
117
+ }
118
+ },
119
+ "required": [
120
+ "extensionId",
121
+ "version",
122
+ "source",
123
+ "scope",
124
+ "priority",
125
+ "status"
126
+ ],
127
+ "title": "ExtensionCatalogEntry",
128
+ "type": "object"
129
+ }
@@ -0,0 +1,185 @@
1
+ {
2
+ "$defs": {
3
+ "ExtensionClientContributionData": {
4
+ "description": "Declarative contribution understood independently by each client.",
5
+ "oneOf": [
6
+ {
7
+ "additionalProperties": false,
8
+ "properties": {
9
+ "body": {
10
+ "type": "string"
11
+ },
12
+ "kind": {
13
+ "const": "notification",
14
+ "type": "string"
15
+ },
16
+ "level": {
17
+ "$ref": "#/$defs/ExtensionNoticeLevel"
18
+ },
19
+ "title": {
20
+ "type": "string"
21
+ }
22
+ },
23
+ "required": [
24
+ "kind",
25
+ "level",
26
+ "title",
27
+ "body"
28
+ ],
29
+ "type": "object"
30
+ },
31
+ {
32
+ "additionalProperties": false,
33
+ "properties": {
34
+ "detail": {
35
+ "type": [
36
+ "string",
37
+ "null"
38
+ ]
39
+ },
40
+ "kind": {
41
+ "const": "status_item",
42
+ "type": "string"
43
+ },
44
+ "label": {
45
+ "type": "string"
46
+ },
47
+ "value": {
48
+ "type": "string"
49
+ }
50
+ },
51
+ "required": [
52
+ "kind",
53
+ "label",
54
+ "value"
55
+ ],
56
+ "type": "object"
57
+ },
58
+ {
59
+ "additionalProperties": false,
60
+ "properties": {
61
+ "command": {
62
+ "$ref": "#/$defs/ExtensionCommandDescriptor"
63
+ },
64
+ "kind": {
65
+ "const": "command",
66
+ "type": "string"
67
+ }
68
+ },
69
+ "required": [
70
+ "kind",
71
+ "command"
72
+ ],
73
+ "type": "object"
74
+ },
75
+ {
76
+ "additionalProperties": false,
77
+ "properties": {
78
+ "data": true,
79
+ "kind": {
80
+ "const": "detail_panel",
81
+ "type": "string"
82
+ },
83
+ "title": {
84
+ "type": "string"
85
+ }
86
+ },
87
+ "required": [
88
+ "kind",
89
+ "title",
90
+ "data"
91
+ ],
92
+ "type": "object"
93
+ },
94
+ {
95
+ "additionalProperties": false,
96
+ "properties": {
97
+ "kind": {
98
+ "const": "form_action",
99
+ "type": "string"
100
+ },
101
+ "schema": true,
102
+ "submitCommand": {
103
+ "type": "string"
104
+ },
105
+ "title": {
106
+ "type": "string"
107
+ }
108
+ },
109
+ "required": [
110
+ "kind",
111
+ "title",
112
+ "schema",
113
+ "submitCommand"
114
+ ],
115
+ "type": "object"
116
+ }
117
+ ]
118
+ },
119
+ "ExtensionCommandDescriptor": {
120
+ "additionalProperties": false,
121
+ "properties": {
122
+ "argumentSchema": true,
123
+ "description": {
124
+ "type": "string"
125
+ },
126
+ "label": {
127
+ "type": "string"
128
+ },
129
+ "name": {
130
+ "type": "string"
131
+ }
132
+ },
133
+ "required": [
134
+ "name",
135
+ "label",
136
+ "description",
137
+ "argumentSchema"
138
+ ],
139
+ "type": "object"
140
+ },
141
+ "ExtensionNoticeLevel": {
142
+ "enum": [
143
+ "info",
144
+ "success",
145
+ "warning",
146
+ "error"
147
+ ],
148
+ "type": "string"
149
+ },
150
+ "ExtensionScope": {
151
+ "description": "Lifetime boundary for extension instances and their owned effects.",
152
+ "enum": [
153
+ "process",
154
+ "session",
155
+ "run",
156
+ "request"
157
+ ],
158
+ "type": "string"
159
+ }
160
+ },
161
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
162
+ "additionalProperties": false,
163
+ "properties": {
164
+ "contribution": {
165
+ "$ref": "#/$defs/ExtensionClientContributionData"
166
+ },
167
+ "contributionId": {
168
+ "type": "string"
169
+ },
170
+ "extensionId": {
171
+ "type": "string"
172
+ },
173
+ "scope": {
174
+ "$ref": "#/$defs/ExtensionScope"
175
+ }
176
+ },
177
+ "required": [
178
+ "contributionId",
179
+ "extensionId",
180
+ "scope",
181
+ "contribution"
182
+ ],
183
+ "title": "ExtensionClientContribution",
184
+ "type": "object"
185
+ }
@@ -0,0 +1,24 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "additionalProperties": false,
4
+ "properties": {
5
+ "argumentSchema": true,
6
+ "description": {
7
+ "type": "string"
8
+ },
9
+ "label": {
10
+ "type": "string"
11
+ },
12
+ "name": {
13
+ "type": "string"
14
+ }
15
+ },
16
+ "required": [
17
+ "name",
18
+ "label",
19
+ "description",
20
+ "argumentSchema"
21
+ ],
22
+ "title": "ExtensionCommandDescriptor",
23
+ "type": "object"
24
+ }
@@ -0,0 +1,68 @@
1
+ {
2
+ "$schema": "https://json-schema.org/draft/2020-12/schema",
3
+ "oneOf": [
4
+ {
5
+ "additionalProperties": false,
6
+ "properties": {
7
+ "data": true,
8
+ "message": {
9
+ "type": [
10
+ "string",
11
+ "null"
12
+ ]
13
+ },
14
+ "status": {
15
+ "const": "success",
16
+ "type": "string"
17
+ }
18
+ },
19
+ "required": [
20
+ "status"
21
+ ],
22
+ "type": "object"
23
+ },
24
+ {
25
+ "additionalProperties": false,
26
+ "properties": {
27
+ "code": {
28
+ "type": "string"
29
+ },
30
+ "message": {
31
+ "type": "string"
32
+ },
33
+ "status": {
34
+ "const": "rejected",
35
+ "type": "string"
36
+ }
37
+ },
38
+ "required": [
39
+ "status",
40
+ "code",
41
+ "message"
42
+ ],
43
+ "type": "object"
44
+ },
45
+ {
46
+ "additionalProperties": false,
47
+ "properties": {
48
+ "code": {
49
+ "type": "string"
50
+ },
51
+ "message": {
52
+ "type": "string"
53
+ },
54
+ "status": {
55
+ "const": "cancelled",
56
+ "type": "string"
57
+ }
58
+ },
59
+ "required": [
60
+ "status",
61
+ "code",
62
+ "message"
63
+ ],
64
+ "type": "object"
65
+ }
66
+ ],
67
+ "title": "ExtensionCommandOutcome"
68
+ }