@sentry/junior-plugin-api 0.100.0 → 0.101.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/README.md +79 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# @sentry/junior-plugin-api
|
|
2
|
+
|
|
3
|
+
This package defines the public contract between Junior and code plugins. The
|
|
4
|
+
exported TypeScript types and runtime validators are authoritative.
|
|
5
|
+
|
|
6
|
+
## Registration
|
|
7
|
+
|
|
8
|
+
Use `defineJuniorPlugin({ manifest, hooks, tasks, cli, model })`. A plugin name
|
|
9
|
+
is a lowercase identifier and is unique within the enabled app plugin set.
|
|
10
|
+
|
|
11
|
+
A plugin may instead be a declarative `plugin.yaml` package when it has no
|
|
12
|
+
host-executed hooks. Do not combine an inline manifest with a second YAML
|
|
13
|
+
definition for the same plugin.
|
|
14
|
+
|
|
15
|
+
## Manifest
|
|
16
|
+
|
|
17
|
+
The manifest declares runtime metadata such as:
|
|
18
|
+
|
|
19
|
+
- plugin identity and description;
|
|
20
|
+
- skill roots and MCP tool sources;
|
|
21
|
+
- provider domains, grants, OAuth, API-header transformations, and safe command
|
|
22
|
+
environment placeholders;
|
|
23
|
+
- runtime dependencies and snapshot installation steps;
|
|
24
|
+
- configuration fields.
|
|
25
|
+
|
|
26
|
+
Manifest values are validated before runtime activation. Secret deployment
|
|
27
|
+
values remain host-only; sandbox-exposed command environment must be explicitly
|
|
28
|
+
safe.
|
|
29
|
+
|
|
30
|
+
## Hooks
|
|
31
|
+
|
|
32
|
+
Plugins may contribute tools, prompt messages, lifecycle work, operational
|
|
33
|
+
reports, migrations, and other typed hook surfaces exported by this package.
|
|
34
|
+
|
|
35
|
+
- Hook context carries the active source, actor, conversation, plugin metadata,
|
|
36
|
+
database, logging, and only the host capabilities required by that hook.
|
|
37
|
+
- Prompt hooks return bounded structured prompt messages rather than mutate the
|
|
38
|
+
core prompt.
|
|
39
|
+
- Tool hooks return model-visible schemas aligned with their executor inputs.
|
|
40
|
+
- Host-owned structured model and embedding calls do not expose provider
|
|
41
|
+
credentials to plugins.
|
|
42
|
+
|
|
43
|
+
## Durable Work
|
|
44
|
+
|
|
45
|
+
- Heartbeat hooks perform bounded periodic maintenance and must be safe to run
|
|
46
|
+
repeatedly.
|
|
47
|
+
- Background tasks are registered by name, receive validated parameters, and
|
|
48
|
+
execute through the host queue/callback lifecycle.
|
|
49
|
+
- `ctx.agent.dispatch` creates durable agent work with an explicit actor,
|
|
50
|
+
destination, source, metadata, and idempotency identity.
|
|
51
|
+
- Completed dispatch and task projections are durable plugin inputs, not an
|
|
52
|
+
invitation to inspect unrestricted conversation state.
|
|
53
|
+
|
|
54
|
+
## Database
|
|
55
|
+
|
|
56
|
+
- Packaged migrations create plugin-owned tables through the host migration
|
|
57
|
+
runner.
|
|
58
|
+
- Generate migration artifacts from the package schema; do not hand-maintain a
|
|
59
|
+
second schema contract.
|
|
60
|
+
- Runtime hooks and CLI actions use host-provided `ctx.db`.
|
|
61
|
+
- Migrations are expand-first, deterministic, ordered by plugin name, and safe
|
|
62
|
+
to retry. A failure blocks upgrade rather than partially enabling the plugin.
|
|
63
|
+
- Cross-plugin or core-table access is a review boundary for trusted app code;
|
|
64
|
+
introduce a facade only when a concrete security or lifecycle boundary
|
|
65
|
+
requires it.
|
|
66
|
+
|
|
67
|
+
## CLI
|
|
68
|
+
|
|
69
|
+
Code plugins may register one namespaced host CLI command with one or more
|
|
70
|
+
subcommands. Core command names win. Actions use the host action wrapper and
|
|
71
|
+
receive plugin metadata, configuration, database, safe output writers, and
|
|
72
|
+
logging—not model, Slack, sandbox, or provider credential context.
|
|
73
|
+
|
|
74
|
+
## Security
|
|
75
|
+
|
|
76
|
+
Plugins and skills follow `../../policies/security.md`,
|
|
77
|
+
`../../policies/data-redaction.md`, and
|
|
78
|
+
`../../policies/provider-boundaries.md`. Skills explain capability use; they do
|
|
79
|
+
not bootstrap runtimes or credentials.
|