@symbioticsec/plugin 0.2.3 → 0.3.6

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.
@@ -0,0 +1,15 @@
1
+ import type { Plugin } from "@symbioticsec/plugin";
2
+ /**
3
+ * Reference workspace adaptor that creates a blank temporary folder per
4
+ * session. Ported from OpenCode's `@opencode-ai/plugin/example-workspace`
5
+ * so plugin authors have a minimal, working starting point.
6
+ *
7
+ * Usage from a plugin package:
8
+ *
9
+ * ```ts
10
+ * import { FolderWorkspacePlugin } from "@symbioticsec/plugin/example-workspace"
11
+ * export default FolderWorkspacePlugin
12
+ * ```
13
+ */
14
+ export declare const FolderWorkspacePlugin: Plugin;
15
+ export default FolderWorkspacePlugin;
@@ -0,0 +1,50 @@
1
+ import { mkdir, rm } from "node:fs/promises";
2
+ import path from "node:path";
3
+ import { tmpdir } from "node:os";
4
+ import { randomUUID } from "node:crypto";
5
+ /**
6
+ * Reference workspace adaptor that creates a blank temporary folder per
7
+ * session. Ported from OpenCode's `@opencode-ai/plugin/example-workspace`
8
+ * so plugin authors have a minimal, working starting point.
9
+ *
10
+ * Usage from a plugin package:
11
+ *
12
+ * ```ts
13
+ * import { FolderWorkspacePlugin } from "@symbioticsec/plugin/example-workspace"
14
+ * export default FolderWorkspacePlugin
15
+ * ```
16
+ */
17
+ export const FolderWorkspacePlugin = async ({ experimental_workspace }) => {
18
+ experimental_workspace.register("folder", {
19
+ name: "Folder",
20
+ description: "Create a blank folder",
21
+ configure(config) {
22
+ // `randomUUID` avoids collision between concurrent sessions more
23
+ // reliably than `Math.random()` and never leaks time-ordered IDs.
24
+ // `os.tmpdir()` respects `TMPDIR`/`TEMP` so tests don't pollute `/tmp`.
25
+ const id = randomUUID();
26
+ return {
27
+ ...config,
28
+ directory: path.join(tmpdir(), "symbiotic-folder", `folder-${id}`),
29
+ };
30
+ },
31
+ async create(config) {
32
+ if (!config.directory)
33
+ return;
34
+ await mkdir(config.directory, { recursive: true });
35
+ },
36
+ async remove(config) {
37
+ if (!config.directory)
38
+ return;
39
+ await rm(config.directory, { recursive: true, force: true });
40
+ },
41
+ target(config) {
42
+ return {
43
+ type: "local",
44
+ directory: config.directory,
45
+ };
46
+ },
47
+ });
48
+ return {};
49
+ };
50
+ export default FolderWorkspacePlugin;
package/dist/index.d.ts CHANGED
@@ -4,6 +4,11 @@ import { type ToolDefinition } from "./tool.js";
4
4
  export * from "./tool.js";
5
5
  export type { Config } from "@symbioticsec/sdk";
6
6
  export type PluginOptions = Record<string, unknown>;
7
+ /**
8
+ * Package-manifest metadata shape used by the host's TUI plugin registry.
9
+ * Plugin authors normally don't write this directly; it's derived from
10
+ * `package.json` and passed into TUI plugin factories as `meta`.
11
+ */
7
12
  export type PluginModule = {
8
13
  id: string;
9
14
  version?: string;
@@ -13,6 +18,27 @@ export type PluginModule = {
13
18
  license?: string;
14
19
  tui?: unknown;
15
20
  };
21
+ /**
22
+ * The strict shape of a **server-only plugin package**'s default export.
23
+ * Mirrors OpenCode's `PluginModule`. A package shipping just a server
24
+ * surface should:
25
+ *
26
+ * ```ts
27
+ * export default {
28
+ * id: "my-plugin",
29
+ * server: async (input) => ({ ... }),
30
+ * } satisfies ServerPluginModule
31
+ * ```
32
+ *
33
+ * The `tui?: never` constraint forces TUI plugins into a separate package
34
+ * (or a separate `./tui` export), matching OpenCode's design where server
35
+ * and tui code never co-habit one module.
36
+ */
37
+ export type ServerPluginModule = {
38
+ id?: string;
39
+ server: Plugin;
40
+ tui?: never;
41
+ };
16
42
  export type ProviderContext = {
17
43
  source: "env" | "config" | "custom" | "api";
18
44
  info: Provider;
@@ -25,8 +51,90 @@ export type PluginInput = {
25
51
  worktree: string;
26
52
  serverUrl: URL;
27
53
  $: BunShell;
54
+ /**
55
+ * Experimental: register workspace adaptors that create and manage the
56
+ * backing environment for a session (e.g. worktrees, remote sandboxes).
57
+ * Adaptors are scoped to the current project. Always provided by the
58
+ * host — matches OpenCode's required-field shape.
59
+ */
60
+ experimental_workspace: {
61
+ register(type: string, adaptor: WorkspaceAdaptor): void;
62
+ };
63
+ };
64
+ /**
65
+ * Metadata describing a single workspace instance: the concrete slot that
66
+ * the adaptor was asked to provision for a project.
67
+ */
68
+ export type WorkspaceInfo = {
69
+ id: string;
70
+ type: string;
71
+ name: string;
72
+ branch: string | null;
73
+ directory: string | null;
74
+ extra: unknown | null;
75
+ projectID: string;
76
+ };
77
+ /**
78
+ * Where the session should dispatch requests. A local target hands work to
79
+ * a directory on the current machine. A remote target hands work to an HTTP
80
+ * endpoint — the adaptor is responsible for any auth headers.
81
+ */
82
+ export type WorkspaceTarget = {
83
+ type: "local";
84
+ directory: string;
85
+ } | {
86
+ type: "remote";
87
+ url: string | URL;
88
+ headers?: HeadersInit;
89
+ };
90
+ /**
91
+ * A workspace adaptor instructs the host how to prepare, describe, target,
92
+ * and tear down the execution environment for a session. Adaptors are
93
+ * registered via `PluginInput.experimental_workspace.register(type, adaptor)`
94
+ * and are keyed by `type` — the first registration of a given `type` wins
95
+ * for the lifetime of the host process.
96
+ *
97
+ * The shape mirrors OpenCode's plugin SDK so OpenCode-compatible workspace
98
+ * adaptors work unchanged.
99
+ *
100
+ * - `name` / `description`: surfaced in the workspace picker UI.
101
+ * - `configure`: derive the final `WorkspaceInfo` (e.g. fill in branch/name defaults).
102
+ * - `create`: provision the workspace, given the session's env vars and
103
+ * optionally a source workspace to clone from.
104
+ * - `remove`: tear down the workspace; called during `deleteWorkspace`.
105
+ * - `target`: return the dispatch target (local directory or remote URL)
106
+ * for this workspace.
107
+ */
108
+ export type WorkspaceAdaptor = {
109
+ name: string;
110
+ description: string;
111
+ configure(info: WorkspaceInfo): WorkspaceInfo | Promise<WorkspaceInfo>;
112
+ create(info: WorkspaceInfo, env: Record<string, string | undefined>, from?: WorkspaceInfo): Promise<void>;
113
+ remove(info: WorkspaceInfo): Promise<void>;
114
+ target(info: WorkspaceInfo): WorkspaceTarget | Promise<WorkspaceTarget>;
115
+ };
116
+ export type Plugin = (input: PluginInput, options?: PluginOptions) => Promise<Hooks>;
117
+ /**
118
+ * Context passed to a `ProviderHook.models` call. `auth` is pre-resolved
119
+ * by the host; it is `undefined` when the provider has no active auth.
120
+ */
121
+ export type ProviderHookContext = {
122
+ auth?: Auth;
123
+ };
124
+ /**
125
+ * A dynamic provider hook: given a provider, return the map of models it
126
+ * should expose. The host merges the returned map onto `provider.models`,
127
+ * overriding any prior entry with the same id.
128
+ *
129
+ * `models` is optional so plugins can register for a provider without
130
+ * necessarily contributing models (useful for auth-only registrations).
131
+ *
132
+ * Multiple hooks with the same `id` are merged in registration order.
133
+ */
134
+ export type ProviderHook = {
135
+ id: string;
136
+ models?: (provider: Provider, ctx: ProviderHookContext) => Promise<Record<string, Model>>;
28
137
  };
29
- export type Plugin = (input: PluginInput) => Promise<Hooks>;
30
138
  type Rule = {
31
139
  key: string;
32
140
  op: "eq" | "neq";
@@ -60,7 +168,7 @@ export type AuthHook = {
60
168
  condition?: (inputs: Record<string, string>) => boolean;
61
169
  when?: Rule;
62
170
  }>;
63
- authorize(inputs?: Record<string, string>): Promise<AuthOuathResult>;
171
+ authorize(inputs?: Record<string, string>): Promise<AuthOAuthResult>;
64
172
  } | {
65
173
  type: "api";
66
174
  label: string;
@@ -95,14 +203,16 @@ export type AuthHook = {
95
203
  }>;
96
204
  })[];
97
205
  };
98
- export type AuthOuathResult = {
206
+ export type AuthOAuthResult = {
99
207
  url: string;
100
208
  instructions: string;
209
+ enterpriseUrl?: string;
101
210
  } & ({
102
211
  method: "auto";
103
212
  callback(): Promise<({
104
213
  type: "success";
105
214
  provider?: string;
215
+ enterpriseUrl?: string;
106
216
  } & ({
107
217
  refresh: string;
108
218
  access: string;
@@ -118,6 +228,7 @@ export type AuthOuathResult = {
118
228
  callback(code: string): Promise<({
119
229
  type: "success";
120
230
  provider?: string;
231
+ enterpriseUrl?: string;
121
232
  } & ({
122
233
  refresh: string;
123
234
  access: string;
@@ -129,6 +240,11 @@ export type AuthOuathResult = {
129
240
  type: "failed";
130
241
  }>;
131
242
  });
243
+ /**
244
+ * @deprecated Use `AuthOAuthResult` instead. This alias preserves the
245
+ * historical misspelling exported from earlier versions of the plugin SDK.
246
+ */
247
+ export type AuthOuathResult = AuthOAuthResult;
132
248
  export interface Hooks {
133
249
  event?: (input: {
134
250
  event: Event;
@@ -138,6 +254,12 @@ export interface Hooks {
138
254
  [key: string]: ToolDefinition;
139
255
  };
140
256
  auth?: AuthHook;
257
+ /**
258
+ * Dynamically contribute models for one or more providers. The host merges
259
+ * each hook's returned record onto `provider.models`, so later hooks
260
+ * override earlier ones by model id. Mirror of OpenCode's provider hook.
261
+ */
262
+ provider?: ProviderHook | ProviderHook[];
141
263
  /**
142
264
  * Called when a new message is received
143
265
  */
@@ -156,6 +278,9 @@ export interface Hooks {
156
278
  }) => Promise<void>;
157
279
  /**
158
280
  * Modify parameters sent to LLM
281
+ *
282
+ * - `maxOutputTokens`: `number` overrides the default cap, `null` clears it
283
+ * entirely (e.g. for reasoning models), `undefined` leaves it unchanged.
159
284
  */
160
285
  "chat.params"?: (input: {
161
286
  sessionID: string;
@@ -168,6 +293,7 @@ export interface Hooks {
168
293
  topP: number;
169
294
  topK: number;
170
295
  options: Record<string, any>;
296
+ maxOutputTokens?: number | null;
171
297
  }) => Promise<void>;
172
298
  "chat.headers"?: (input: {
173
299
  sessionID: string;
@@ -237,6 +363,26 @@ export interface Hooks {
237
363
  context: string[];
238
364
  prompt?: string;
239
365
  }) => Promise<void>;
366
+ /**
367
+ * Called after session compaction completes but before the synthetic
368
+ * "continue" user turn is added. Setting `output.enabled = false`
369
+ * suppresses the autocontinue message.
370
+ *
371
+ * Input carries the full context the host had when deciding to compact:
372
+ * - `overflow` is `true` when compaction was triggered by a context-size
373
+ * breach (vs. a manual `/compact` or an auto-interval). Plugins can use
374
+ * this to skip the auto-continue only for overflow-driven compactions.
375
+ */
376
+ "experimental.compaction.autocontinue"?: (input: {
377
+ sessionID: string;
378
+ agent: string;
379
+ model: Model;
380
+ provider: ProviderContext;
381
+ message: UserMessage;
382
+ overflow: boolean;
383
+ }, output: {
384
+ enabled: boolean;
385
+ }) => Promise<void>;
240
386
  "experimental.text.complete"?: (input: {
241
387
  sessionID: string;
242
388
  messageID: string;
package/dist/shell.d.ts CHANGED
@@ -1,3 +1,4 @@
1
+ import type { BufferEncoding } from "typescript";
1
2
  export type ShellFunction = (input: Uint8Array) => Uint8Array;
2
3
  export type ShellExpression = {
3
4
  toString(): string;
package/dist/tui.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import type { SymbioticClient, Event, LspStatus, McpStatus, Todo, Message, Part, Provider, PermissionRequest, QuestionRequest, SessionStatus, Workspace, Config as SdkConfig } from "@symbioticsec/sdk/v2";
2
- import type { CliRenderer, ParsedKey, RGBA } from "@opentui/core";
1
+ import type { SymbioticClient, Event, LspStatus, McpStatus, Todo, Message, Part, Provider, PermissionRequest, QuestionRequest, SessionStatus, Workspace, Config as SdkConfig, AgentPart, FilePart, TextPart } from "@symbioticsec/sdk/v2";
2
+ import type { CliRenderer, ParsedKey, RGBA, SlotMode } from "@opentui/core";
3
3
  import type { JSX, SolidPlugin } from "@opentui/solid";
4
4
  import type { Config as PluginConfig, PluginModule, PluginOptions } from "./index.js";
5
5
  export type { CliRenderer, SlotMode } from "@opentui/core";
@@ -239,10 +239,83 @@ export type TuiSidebarFileItem = {
239
239
  additions: number;
240
240
  deletions: number;
241
241
  };
242
- export type TuiSlotMap = {
242
+ /**
243
+ * Snapshot of the prompt component's current value. Mirrors OpenCode's
244
+ * shape so plugins written for either host can read/write the prompt
245
+ * uniformly.
246
+ */
247
+ export type TuiPromptInfo = {
248
+ input: string;
249
+ mode?: "normal" | "shell";
250
+ parts: (Omit<FilePart, "id" | "messageID" | "sessionID"> | Omit<AgentPart, "id" | "messageID" | "sessionID"> | (Omit<TextPart, "id" | "messageID" | "sessionID"> & {
251
+ source?: {
252
+ text: {
253
+ start: number;
254
+ end: number;
255
+ value: string;
256
+ };
257
+ };
258
+ }))[];
259
+ };
260
+ /**
261
+ * Imperative handle to the prompt component. Wired up by the host when a
262
+ * plugin (or the built-in view) renders a `ui.Prompt` and subscribes via
263
+ * the `ref` callback on `TuiPromptProps`.
264
+ */
265
+ export type TuiPromptRef = {
266
+ focused: boolean;
267
+ current: TuiPromptInfo;
268
+ set(prompt: TuiPromptInfo): void;
269
+ reset(): void;
270
+ blur(): void;
271
+ focus(): void;
272
+ submit(): void;
273
+ };
274
+ /**
275
+ * Props accepted by the `ui.Prompt` component and by the enriched
276
+ * `home_prompt` / `session_prompt` slots.
277
+ */
278
+ export type TuiPromptProps = {
279
+ sessionID?: string;
280
+ workspaceID?: string;
281
+ visible?: boolean;
282
+ disabled?: boolean;
283
+ onSubmit?: () => void;
284
+ ref?: (ref: TuiPromptRef | undefined) => void;
285
+ hint?: JSX.Element;
286
+ right?: JSX.Element;
287
+ showPlaceholder?: boolean;
288
+ placeholders?: {
289
+ normal?: string[];
290
+ shell?: string[];
291
+ };
292
+ };
293
+ /**
294
+ * The built-in slots the host renders. Plugins can extend this via the
295
+ * `Slots` type parameter on `TuiSlotPlugin` / `TuiSlots.register`.
296
+ */
297
+ export type TuiHostSlotMap = {
243
298
  app: {};
244
299
  home_logo: {};
245
300
  home_bottom: {};
301
+ home_prompt: {
302
+ workspace_id?: string;
303
+ ref?: (ref: TuiPromptRef | undefined) => void;
304
+ };
305
+ home_prompt_right: {
306
+ workspace_id?: string;
307
+ };
308
+ home_footer: {};
309
+ session_prompt: {
310
+ session_id: string;
311
+ visible?: boolean;
312
+ disabled?: boolean;
313
+ on_submit?: () => void;
314
+ ref?: (ref: TuiPromptRef | undefined) => void;
315
+ };
316
+ session_prompt_right: {
317
+ session_id: string;
318
+ };
246
319
  sidebar_title: {
247
320
  session_id: string;
248
321
  title: string;
@@ -255,15 +328,34 @@ export type TuiSlotMap = {
255
328
  session_id: string;
256
329
  };
257
330
  };
331
+ export type TuiSlotMap<Slots extends Record<string, object> = {}> = TuiHostSlotMap & Slots;
332
+ type TuiSlotShape<Name extends string, Slots extends Record<string, object>> = Name extends keyof TuiHostSlotMap ? TuiHostSlotMap[Name] : Name extends keyof Slots ? Slots[Name] : Record<string, unknown>;
333
+ /**
334
+ * Props for `ui.Slot` — render a named slot and, optionally, provide a
335
+ * fallback child when no plugin has registered a renderer.
336
+ */
337
+ export type TuiSlotProps<Name extends string = string, Slots extends Record<string, object> = {}> = {
338
+ name: Name;
339
+ mode?: SlotMode;
340
+ children?: JSX.Element;
341
+ } & TuiSlotShape<Name, Slots>;
258
342
  export type TuiSlotContext = {
259
343
  theme: TuiTheme;
260
344
  };
261
- type SlotCore = SolidPlugin<TuiSlotMap, TuiSlotContext>;
262
- export type TuiSlotPlugin = Omit<SlotCore, "id"> & {
345
+ /**
346
+ * `TuiSlotPlugin` is generic over extra slot maps so plugins can declare
347
+ * their own named slots with full TypeScript safety. The built-in
348
+ * `TuiHostSlotMap` is always merged in.
349
+ */
350
+ type SlotCore<Slots extends Record<string, object> = {}> = SolidPlugin<TuiSlotMap<Slots>, TuiSlotContext>;
351
+ export type TuiSlotPlugin<Slots extends Record<string, object> = {}> = Omit<SlotCore<Slots>, "id"> & {
263
352
  id?: never;
264
353
  };
265
354
  export type TuiSlots = {
266
- register: (plugin: TuiSlotPlugin) => string;
355
+ register: {
356
+ (plugin: TuiSlotPlugin): string;
357
+ <Slots extends Record<string, object>>(plugin: TuiSlotPlugin<Slots>): string;
358
+ };
267
359
  };
268
360
  export type TuiEventBus = {
269
361
  on: <Type extends Event["type"]>(type: Type, handler: (event: Extract<Event, {
@@ -322,6 +414,11 @@ export type TuiPluginApi = {
322
414
  command: {
323
415
  register: (cb: () => TuiCommand[]) => () => void;
324
416
  trigger: (value: string) => void;
417
+ /**
418
+ * Open the command palette programmatically. Useful for slash-commands
419
+ * that should surface a follow-up picker.
420
+ */
421
+ show: () => void;
325
422
  };
326
423
  route: {
327
424
  register: (routes: TuiRouteDefinition[]) => () => void;
@@ -334,6 +431,16 @@ export type TuiPluginApi = {
334
431
  DialogConfirm: (props: TuiDialogConfirmProps) => JSX.Element;
335
432
  DialogPrompt: (props: TuiDialogPromptProps) => JSX.Element;
336
433
  DialogSelect: <Value = unknown>(props: TuiDialogSelectProps<Value>) => JSX.Element;
434
+ /**
435
+ * Render a named slot inline. `children` renders as a fallback when no
436
+ * plugin has registered a renderer for `name`.
437
+ */
438
+ Slot: <Name extends string>(props: TuiSlotProps<Name>) => JSX.Element | null;
439
+ /**
440
+ * Render the shared prompt component. Pass `ref` to receive a
441
+ * `TuiPromptRef` handle (focus/blur/submit/set/reset).
442
+ */
443
+ Prompt: (props: TuiPromptProps) => JSX.Element;
337
444
  toast: (input: TuiToast) => void;
338
445
  dialog: TuiDialogStack;
339
446
  };
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "$schema": "https://json.schemastore.org/package.json",
3
3
  "name": "@symbioticsec/plugin",
4
- "version": "0.2.3",
4
+ "version": "0.3.6",
5
5
  "type": "module",
6
6
  "license": "© Symbiotic Security. All rights reserved. Use is subject to the Legal Agreements outlined here: https://docs.google.com/document/d/1jwTKCmTBKdtXkIDFWgfw4T00govAv5tLOPoO96pDFLU",
7
7
  "scripts": {
@@ -20,6 +20,10 @@
20
20
  "./tui": {
21
21
  "import": "./dist/tui.js",
22
22
  "types": "./dist/tui.d.ts"
23
+ },
24
+ "./example-workspace": {
25
+ "import": "./dist/example-workspace.js",
26
+ "types": "./dist/example-workspace.d.ts"
23
27
  }
24
28
  },
25
29
  "peerDependencies": {
@@ -38,7 +42,7 @@
38
42
  "dist"
39
43
  ],
40
44
  "dependencies": {
41
- "@symbioticsec/sdk": "0.2.3",
45
+ "@symbioticsec/sdk": "0.3.6",
42
46
  "zod": "4.1.8"
43
47
  },
44
48
  "devDependencies": {