@alisio/sdk 0.1.0-alpha.2 → 0.1.0-alpha.20

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.
Files changed (4) hide show
  1. package/README.md +84 -42
  2. package/dist/index.d.ts +1370 -3
  3. package/dist/index.js +56 -0
  4. package/package.json +1 -1
package/README.md CHANGED
@@ -1,7 +1,23 @@
1
1
  # @alisio/sdk
2
2
 
3
- The typed plugin contract for [Alisio](https://github.com/GustavoGutierrez/alisio). Types plus two tiny
4
- helpers (`definePlugin`, `textResult`); no runtime dependencies and no provider SDKs.
3
+ **The typed plugin contract for [Alisio](https://github.com/GustavoGutierrez/alisio).** Types plus
4
+ two tiny helpers (`definePlugin`, `textResult`) — no runtime dependencies and no provider SDKs.
5
+
6
+ ## What it is
7
+
8
+ `@alisio/sdk` is what plugins depend on. It declares the `Plugin` and `PluginAPI` shapes, the tool
9
+ and provider contracts, compaction and session hooks, the SQLite storage port and the extension
10
+ points. A plugin ships JavaScript, declares the `alisio-plugin` npm keyword and lists
11
+ `@alisio/sdk` as a peer dependency. Because the package is types-only plus helpers, it is safe to
12
+ import from any runtime Alisio runs on.
13
+
14
+ ## Installation
15
+
16
+ ```sh
17
+ npm i @alisio/sdk # peer dependency of every plugin; use it in devDependencies too
18
+ ```
19
+
20
+ ## Quick start: your first plugin
5
21
 
6
22
  ```ts
7
23
  import { definePlugin, textResult } from "@alisio/sdk";
@@ -24,35 +40,70 @@ export default definePlugin({
24
40
  });
25
41
  ```
26
42
 
43
+ Load it with `alisio --plugin ./dist/index.js` (path) or `alisio install npm:acme-hello` (npm
44
+ package). See [Writing plugins](https://gustavogutierrez.github.io/alisio/plugins) for the full
45
+ walkthrough including tool permissions, naming/prefix rules and an example package.
46
+
47
+ ## The PluginAPI
48
+
49
+ Everything a plugin registers is removed automatically when it unloads; every `register`/`on`
50
+ returns an unregister function.
51
+
52
+ - **tools** — `tools.register(ToolDefinition)`; effects `read | write | process | external |
53
+ internal`, optional `paths()` for write checks, `concurrent` for same-turn parallel calls.
54
+ - **commands** — `commands.register(name, handler, { description?, argumentHint? })`, invoked as
55
+ `/command plugin.id:name args`.
56
+ - **events** — versioned `RunEvent`s (`schemaVersion: 1`).
57
+ - **context** — `context.register(() => Promise<string>)` adds text to the model context.
58
+ - **resources** — `skills(path)`, `prompts(path)`, `agents(path)` and `list(kind)` for skill,
59
+ prompt-template and agent-definition directories.
60
+ - **state** — small per-plugin JSON state persisted in the session database.
61
+ - **compaction** — `compaction.register({ beforeCompact, afterCompact })` contributes instructions,
62
+ extra summarizer output fields, recalled context and reports.
63
+ - **session** — `session.onStart(info)` (text injected on a fresh session) and
64
+ `session.onEnd(info)` (called on `/clear`, `/exit`, quit; bounded by a timeout).
65
+ - **model** — provider-agnostic `model.complete(request)`; plugins never import provider SDKs.
66
+ - **models** — credential-free `models.list()` / `models.resolve(reference)` over configured
67
+ `/connect` profiles.
68
+ - **providers** — `providers.register(registration)` adds a selectable model provider to `/connect`;
69
+ registrations coexist instead of competing.
70
+ - **categories** — declare `categories` on `Plugin`/`PluginMetadata` from the accepted set:
71
+ `model-provider`, `methodology-harness`, `memory`, `subagents`, `search`, `tools`, `security`,
72
+ `analytics`, `mcp`, `storage`, `ui` (see the
73
+ [plugin categories table](https://gustavogutierrez.github.io/alisio/plugins#plugin-categories)).
74
+ The TUI groups `/plugins` rows by the first category, falling back to "General"; the host
75
+ derives `model-provider` automatically when a plugin registers providers.
76
+ - **storage** — `storage.sqlite(path)` opens a private (0600) SQLite file (FTS5 available); the
77
+ host provides the driver, so plugins never depend on a specific runtime.
78
+ - **sessions** — child sessions (`spawn`, `create`, `run`, `get`, `children`, `cancel`, `enqueue`,
79
+ …): separate conversations with fresh context and narrowed permissions that never exceed the
80
+ parent.
81
+ - **ui** — `status`, `panel`, `select`, `askQuestions`, `open`, `interactive()`; interactive-only
82
+ calls resolve `undefined` headless instead of hanging.
83
+
27
84
  ## Extension points
28
85
 
29
- Typed, generic extension points let plugins replace parts of the experience without core
30
- changes. Today: `mascot`, `startup-screen` and `websearch`.
86
+ Typed, generic extension points let plugins replace parts of the experience without core changes.
87
+ Today: `mascot`, `startup-screen` and `websearch`.
31
88
 
32
89
  ```ts
33
90
  api.extensions.register("mascot", {
34
91
  id: "kite",
35
92
  render: ({ terminal }) => (terminal.unicode ? [" ◢◣", " ◢██◣", " ◥██◤", " ◥◤"] : [" /\\", " / \\", " \\ /", " \\/"]),
36
93
  }, { priority: 10 });
37
-
38
- api.extensions.register("websearch", {
39
- id: "brave-example",
40
- search: async (query) => [{ title: "...", url: "https://...", snippet: "..." }],
41
- }, { priority: 10 });
42
94
  ```
43
95
 
44
- The highest `priority` wins; ties break by plugin `id`, then registration order, and are reported
45
- as `extension_conflict`. A renderable provider (`mascot`, `startup-screen`) receives only its
46
- context (`terminal.color`, `unicode`, `columns`); its output is sanitized and clamped, and a
47
- failing provider falls back to the default. `websearch` fully replaces Alisio's built-in
48
- search-provider resolution while registered (a throwing provider also falls back, with a
49
- diagnostic). A declarative `extensions: { mascot, "startup-screen", websearch }` field on the
50
- plugin is also accepted. Plugins are identified by `id` (not `name`).
96
+ The highest `priority` wins; ties break by plugin `id`, then registration order (reported as
97
+ `extension_conflict`). A renderable provider receives only its context (`terminal.color`,
98
+ `unicode`, `columns`); output is sanitized and clamped, and a failing provider falls back to the
99
+ default. `websearch` fully replaces Alisio's built-in search-provider resolution while registered.
100
+ A declarative `extensions` field on the plugin is accepted too, at priority 0. Plugins are
101
+ identified by `id`, not `name`.
51
102
 
52
103
  ## Prompt templates
53
104
 
54
- `api.resources.prompts("./prompts")` registers a directory of Markdown templates that become
55
- slash commands (for example `/review src/app.ts`):
105
+ `api.resources.prompts("./prompts")` registers a directory of Markdown templates that become slash
106
+ commands (for example `/review src/app.ts`):
56
107
 
57
108
  ```md
58
109
  ---
@@ -67,27 +118,18 @@ Review $1 carefully. Extra focus: $ARGUMENTS
67
118
  Precedence: built-in < plugin < user (`~/.config/alisio/prompts`) < trusted project
68
119
  (`.alisio/prompts`).
69
120
 
70
- ## Child sessions, panels and choices
71
-
72
- Generic building blocks used by the built-in subagents plugin and available to any plugin:
73
-
74
- - `api.sessions.spawn/run/cancel/enqueue/...`: child sessions with a parent link, fresh context
75
- and narrowed permissions (a child never exceeds its parent); aborting a parent aborts them.
76
- - `api.ui.panel(id, { title, nodes, action })`: a collapsible tree under the TUI editor.
77
- - `api.ui.select({ title, options })`: ask the user to choose one (resolves `undefined` headless).
78
- - `api.ui.askQuestions({ questions, session?, label?, signal? })`: ask 1-4 multiple-choice questions
79
- (2-4 options each, an optional `recommended` one); resolves every question id `undefined` headless.
80
- `session`/`label` attribute the question to the asking (sub)session, mirroring `ApprovalRequest`.
81
- - `api.ui.interactive()`: true when an interactive UI is bound at all (never per-session), so a
82
- child session under an interactive root can safely call `select`/`askQuestions` too.
83
- - `api.ui.open(sessionId)`, `api.resources.agents(dir)`, `api.resources.list(kind)`.
84
- - `ToolContext.label`: who is asking (an agent path such as `"general › explore"`), set for tool
85
- calls made by a labeled child session; mirrors `ApprovalRequest.label`.
86
- - `ToolDefinition.concurrent`: run alongside other read/concurrent calls of the same turn.
87
-
88
- The API covers tools, commands, events, context providers, compaction hooks, session start/end
89
- hooks, provider-agnostic `model.complete`, a SQLite storage port and UI status. Publish plugins as
90
- JavaScript with the `alisio-plugin` keyword and `@alisio/sdk` as a peer dependency. Guide:
91
- [Writing plugins](https://gustavogutierrez.github.io/alisio/plugins).
92
-
93
- Maintainer: Gustavo Gutiérrez · License: MIT
121
+ ## Publishing
122
+
123
+ Publish plugins as JavaScript with the `alisio-plugin` keyword and `@alisio/sdk` as a peer
124
+ dependency; the entry resolves from `exports["."]`, then `main`, then `./index.js`. Guide:
125
+ [Writing plugins](https://gustavogutierrez.github.io/alisio/plugins) ·
126
+ [Publishing](https://gustavogutierrez.github.io/alisio/publishing).
127
+
128
+ ## Requirements
129
+
130
+ Node.js **>= 22.16** (types-only package; consumers run on Node or Bun).
131
+
132
+ ## License
133
+
134
+ MIT. Maintained by Gustavo Gutiérrez Mercado. Source: <https://github.com/GustavoGutierrez/alisio> ·
135
+ npm: <https://www.npmjs.com/settings/alisio/packages>.