@tianshu-ai/tianshu 0.3.0

package/packages/plugin-sdk/dist/client.js

@@ -0,0 +1,96 @@
+// Client-side plugin authoring types. Imported as
+// `@tianshu/plugin-sdk/client`.
+//
+// The chat shell's PluginRegistry expects a plugin's client module to
+// export a `components` map keyed by the strings used in the manifest's
+// `contributes.{rightPanels|sidebarSections|composerActions}.component`.
+function globalSlot() {
+    // `globalThis` is the same in node, browser, and worker runtimes.
+    return globalThis;
+}
+/** Host-only: install the live `useComposer` accessor. The web bundle
+ *  calls this once on bootstrap with a function that reads from its
+ *  React context. */
+export function __installUseComposer(fn) {
+    globalSlot().__tianshuPluginSdkComposer__ = fn;
+}
+/** Host-only: clear the installed accessor. Used by tests so each
+ *  test starts with a clean slate; production code should never
+ *  call this. */
+export function __resetUseComposerForTest() {
+    delete globalSlot().__tianshuPluginSdkComposer__;
+}
+export function useComposer() {
+    const fn = globalSlot().__tianshuPluginSdkComposer__;
+    if (!fn) {
+        throw new Error("useComposer() called without a host: plugin SDK has no live ComposerApi. " +
+            "If you are seeing this in a test, install one with __installUseComposer().");
+    }
+    return fn();
+}
+function openFileSlot() {
+    return globalThis;
+}
+/** Host or files-plugin only: register an OpenFileApi. The host
+ *  installs a fallback at bootstrap; the Files plugin overrides
+ *  it on mount with its dialog-based implementation. Last writer
+ *  wins. */
+export function __installOpenFileApi(api) {
+    openFileSlot().__tianshuPluginSdkOpenFile__ = api;
+}
+/** Test helper. */
+export function __resetOpenFileApiForTest() {
+    delete openFileSlot().__tianshuPluginSdkOpenFile__;
+}
+/** Hook returning the live `open(path)` callable. Stable across
+ *  re-renders — always reads from the slot, so a late
+ *  __installOpenFileApi() takes effect on the next call without
+ *  forcing a re-mount. Throws only if absolutely no implementation
+ *  has ever been installed (which means the host bootstrap was
+ *  skipped). */
+// ─── PluginConfigForm — re-export of the host's auto-generated
+// config form, exposed so a plugin's own admin page can fold it
+// in alongside its richer UI (Sandbox status / build history /
+// etc.) instead of getting a duplicated "Settings" sidebar entry.
+//
+// Same install-once + globalSlot trick. Host installs the
+// component on bootstrap; plugin imports `PluginConfigForm` and
+// renders <PluginConfigForm pluginId="microsandbox" /> wherever
+// makes sense. The form looks up its own data from the live
+// plugin store, so the plugin only needs to pass the id.
+import * as React from "react";
+function pluginConfigFormSlot() {
+    return globalThis;
+}
+export function __installPluginConfigForm(C) {
+    pluginConfigFormSlot().__tianshuPluginSdkPluginConfigForm__ = C;
+}
+export function __resetPluginConfigFormForTest() {
+    delete pluginConfigFormSlot().__tianshuPluginSdkPluginConfigForm__;
+}
+/** Renders the auto-generated config form for `pluginId`. If the
+ *  plugin has no `configSchema` or no fields, renders nothing
+ *  (so the calling component can drop it in unconditionally). */
+export const PluginConfigForm = (props) => {
+    const C = pluginConfigFormSlot().__tianshuPluginSdkPluginConfigForm__;
+    if (!C)
+        return null;
+    return React.createElement(C, props);
+};
+export function useOpenFile() {
+    return (path) => {
+        const api = openFileSlot().__tianshuPluginSdkOpenFile__;
+        if (!api) {
+            // Last-resort UX so the click does *something* useful even
+            // before any registrar has installed: stick the path in the
+            // URL bar of a new tab. Never reachable in production where
+            // the host installs a fallback at bootstrap.
+            const cleaned = path.replace(/^workspace:\/\/+/, "/");
+            const url = `/api/p/files/raw?path=${encodeURIComponent(cleaned)}`;
+            window.open(url, "_blank", "noopener");
+            return;
+        }
+        api.open(path);
+    };
+}
+//# sourceMappingURL=client.js.map

package/packages/plugin-sdk/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,kDAAkD;AAClD,gCAAgC;AAChC,EAAE;AACF,sEAAsE;AACtE,wEAAwE;AACxE,yEAAyE;AA4KzE,SAAS,UAAU;IACjB,kEAAkE;IAClE,OAAO,UAA2C,CAAC;AACrD,CAAC;AAED;;qBAEqB;AACrB,MAAM,UAAU,oBAAoB,CAAC,EAAqB;IACxD,UAAU,EAAE,CAAC,4BAA4B,GAAG,EAAE,CAAC;AACjD,CAAC;AAED;;iBAEiB;AACjB,MAAM,UAAU,yBAAyB;IACvC,OAAO,UAAU,EAAE,CAAC,4BAA4B,CAAC;AACnD,CAAC;AAED,MAAM,UAAU,WAAW;IACzB,MAAM,EAAE,GAAG,UAAU,EAAE,CAAC,4BAA4B,CAAC;IACrD,IAAI,CAAC,EAAE,EAAE,CAAC;QACR,MAAM,IAAI,KAAK,CACb,2EAA2E;YACzE,4EAA4E,CAC/E,CAAC;IACJ,CAAC;IACD,OAAO,EAAE,EAAE,CAAC;AACd,CAAC;AA2BD,SAAS,YAAY;IACnB,OAAO,UAA2C,CAAC;AACrD,CAAC;AAED;;;YAGY;AACZ,MAAM,UAAU,oBAAoB,CAAC,GAAgB;IACnD,YAAY,EAAE,CAAC,4BAA4B,GAAG,GAAG,CAAC;AACpD,CAAC;AAED,mBAAmB;AACnB,MAAM,UAAU,yBAAyB;IACvC,OAAO,YAAY,EAAE,CAAC,4BAA4B,CAAC;AACrD,CAAC;AAED;;;;;gBAKgB;AAChB,gEAAgE;AAChE,gEAAgE;AAChE,+DAA+D;AAC/D,kEAAkE;AAClE,EAAE;AACF,0DAA0D;AAC1D,gEAAgE;AAChE,gEAAgE;AAChE,4DAA4D;AAC5D,yDAAyD;AAEzD,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAe/B,SAAS,oBAAoB;IAC3B,OAAO,UAAmD,CAAC;AAC7D,CAAC;AAED,MAAM,UAAU,yBAAyB,CACvC,CAA6C;IAE7C,oBAAoB,EAAE,CAAC,oCAAoC,GAAG,CAAC,CAAC;AAClE,CAAC;AAED,MAAM,UAAU,8BAA8B;IAC5C,OAAO,oBAAoB,EAAE,CAAC,oCAAoC,CAAC;AACrE,CAAC;AAED;;iEAEiE;AACjE,MAAM,CAAC,MAAM,gBAAgB,GAC3B,CAAC,KAAK,EAAE,EAAE;IACR,MAAM,CAAC,GAAG,oBAAoB,EAAE,CAAC,oCAAoC,CAAC;IACtE,IAAI,CAAC,CAAC;QAAE,OAAO,IAAI,CAAC;IACpB,OAAO,KAAK,CAAC,aAAa,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC,CAAC;AAEJ,MAAM,UAAU,WAAW;IACzB,OAAO,CAAC,IAAY,EAAQ,EAAE;QAC5B,MAAM,GAAG,GAAG,YAAY,EAAE,CAAC,4BAA4B,CAAC;QACxD,IAAI,CAAC,GAAG,EAAE,CAAC;YACT,2DAA2D;YAC3D,4DAA4D;YAC5D,4DAA4D;YAC5D,6CAA6C;YAC7C,MAAM,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,kBAAkB,EAAE,GAAG,CAAC,CAAC;YACtD,MAAM,GAAG,GAAG,yBAAyB,kBAAkB,CAAC,OAAO,CAAC,EAAE,CAAC;YACnE,MAAM,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,UAAU,CAAC,CAAC;YACvC,OAAO;QACT,CAAC;QACD,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACjB,CAAC,CAAC;AACJ,CAAC"}

package/packages/plugin-sdk/dist/index.d.ts

@@ -0,0 +1,9 @@
+export * from "./capabilities.js";
+export * from "./manifest.js";
+export * from "./server.js";
+export * from "./agent-loop.js";
+export * from "./session-inbox.js";
+export * from "./catalog.js";
+export * from "./lsp.js";
+export { McpToolset, textOfMcpContent, type McpEndpointResolver, type McpToolDescriptor, type McpToolFilter, type McpToolsetEntry, type McpToolsetOptions, type McpToolsetSnapshot, type ToolsetProvider, } from "./mcp-toolset.js";
+//# sourceMappingURL=index.d.ts.map

package/packages/plugin-sdk/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAWA,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,KAAK,mBAAmB,EACxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,kBAAkB,EACvB,KAAK,eAAe,GACrB,MAAM,kBAAkB,CAAC"}

package/packages/plugin-sdk/dist/index.js

@@ -0,0 +1,19 @@
+// @tianshu/plugin-sdk — server-side plugin authoring types.
+//
+// A plugin is one directory: manifest.json + server entry + client
+// entry (see ADR-0003 §1). The server entry exports `activate(ctx)`
+// (and optional `deactivate()`) and types from this module guide the
+// shape of the returned exports.
+//
+// Client-side types live at `@tianshu/plugin-sdk/client` so a plugin
+// author can install just the SDK in their package and pull both
+// halves from one source.
+export * from "./capabilities.js";
+export * from "./manifest.js";
+export * from "./server.js";
+export * from "./agent-loop.js";
+export * from "./session-inbox.js";
+export * from "./catalog.js";
+export * from "./lsp.js";
+export { McpToolset, textOfMcpContent, } from "./mcp-toolset.js";
+//# sourceMappingURL=index.js.map

package/packages/plugin-sdk/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,4DAA4D;AAC5D,EAAE;AACF,mEAAmE;AACnE,oEAAoE;AACpE,qEAAqE;AACrE,iCAAiC;AACjC,EAAE;AACF,qEAAqE;AACrE,iEAAiE;AACjE,0BAA0B;AAE1B,cAAc,mBAAmB,CAAC;AAClC,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,iBAAiB,CAAC;AAChC,cAAc,oBAAoB,CAAC;AACnC,cAAc,cAAc,CAAC;AAC7B,cAAc,UAAU,CAAC;AACzB,OAAO,EACL,UAAU,EACV,gBAAgB,GAQjB,MAAM,kBAAkB,CAAC"}

package/packages/plugin-sdk/dist/lsp.d.ts

@@ -0,0 +1,32 @@
+export interface LspDiagnoseInput {
+    /** Absolute path of the file the agent just wrote/edited.
+     *  Must live under the calling tenant's workspace; the host
+     *  refuses paths above the tenant boundary as a safety
+     *  measure (ADR-0005 §multi-tenancy). */
+    filePath: string;
+    /** Post-edit contents of the file. Pushed to the LS via
+     *  `textDocument/didChange` before requesting diagnostics. */
+    contents: string;
+}
+export interface LspDiagnoseResult {
+    /** Formatted diagnostic block suitable to append to tool
+     *  output. Empty string when the LS reported no diagnostics
+     *  or when LSP didn't run for this file (no matching
+     *  language, capability disabled, etc). */
+    text: string;
+    /** True if at least one diagnostic was ERROR-severity. Plugins
+     *  may use this to flag the tool result without dropping the
+     *  edit's success state. */
+    hasErrors: boolean;
+    /** Set when diagnostics were unavailable for a known reason
+     *  (missing binary, LS crashed, timeout). The plugin should
+     *  surface this as a one-line note, not a tool failure. */
+    unavailable?: string;
+}
+/** The shape registered at `host.lsp`. */
+export interface LspCapability {
+    /** Diagnose `input.filePath` and return formatted output.
+     *  Always resolves; never throws. */
+    diagnoseAfterEdit(input: LspDiagnoseInput): Promise<LspDiagnoseResult>;
+}
+//# sourceMappingURL=lsp.d.ts.map

package/packages/plugin-sdk/dist/lsp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp.d.ts","sourceRoot":"","sources":["../src/lsp.ts"],"names":[],"mappings":"AAkBA,MAAM,WAAW,gBAAgB;IAC/B;;;6CAGyC;IACzC,QAAQ,EAAE,MAAM,CAAC;IACjB;kEAC8D;IAC9D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,iBAAiB;IAChC;;;+CAG2C;IAC3C,IAAI,EAAE,MAAM,CAAC;IACb;;gCAE4B;IAC5B,SAAS,EAAE,OAAO,CAAC;IACnB;;+DAE2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,0CAA0C;AAC1C,MAAM,WAAW,aAAa;IAC5B;yCACqC;IACrC,iBAAiB,CAAC,KAAK,EAAE,gBAAgB,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAAC;CACxE"}

package/packages/plugin-sdk/dist/lsp.js

@@ -0,0 +1,19 @@
+// Plugin-side surface of the host's `host.lsp` capability.
+//
+// The host (server/src/lsp/) owns the LSP manager: spawning,
+// pooling, tenant-scoping, auto-install, debounce, formatting.
+// Plugins don't see any of that; they just call
+// `diagnoseAfterEdit({filePath, contents})` and append the
+// returned text to their tool result.
+//
+// The capability is exclusive (one provider per host) and the
+// only consumer today is `plugins/files`. We expose it through
+// SDK types so a future plugin (say a refactor tool) doesn't
+// have to re-import server internals to consume diagnostics.
+//
+// Failure model: the call NEVER throws. LSP outages, missing
+// language servers, timeouts — all degrade to a cleanly-typed
+// result with `unavailable` set. The plugin's tool reports
+// success on the underlying edit regardless.
+export {};
+//# sourceMappingURL=lsp.js.map

package/packages/plugin-sdk/dist/lsp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lsp.js","sourceRoot":"","sources":["../src/lsp.ts"],"names":[],"mappings":"AAAA,2DAA2D;AAC3D,EAAE;AACF,6DAA6D;AAC7D,+DAA+D;AAC/D,gDAAgD;AAChD,2DAA2D;AAC3D,sCAAsC;AACtC,EAAE;AACF,8DAA8D;AAC9D,+DAA+D;AAC/D,6DAA6D;AAC7D,6DAA6D;AAC7D,EAAE;AACF,6DAA6D;AAC7D,8DAA8D;AAC9D,2DAA2D;AAC3D,6CAA6C"}

package/packages/plugin-sdk/dist/manifest.d.ts

@@ -0,0 +1,423 @@
+export interface PluginManifest {
+    /** ^[a-z0-9][a-z0-9-]{1,30}$ */
+    id: string;
+    /** semver */
+    version: string;
+    displayName: string;
+    description?: string;
+    author?: string;
+    license?: string;
+    /**
+     * Declarative permission strings.
+     *
+     * ⚠️ **NOT enforced in v0.** Plugins run with full host privileges:
+     * they share the tenant DB, the workspace filesystem, and the
+     * tenant config write surface with each other. The host does not
+     * sandbox plugins from each other and does not check this list
+     * before granting access to anything. Authoring plugins as if
+     * these were enforced is fine — it documents intent for the user
+     * — but **never trust this list as a security boundary**.
+     *
+     * Real enforcement (capability gating, route ACLs, plugin-vs-plugin
+     * isolation) lands when the catalog ships third-party plugins;
+     * see `docs/architecture/plugins.md` §"Trust model".
+     */
+    permissions?: string[];
+    /**
+     * Capabilities (ADR-0004 §3) this plugin claims to provide. Each
+     * entry must be a member of `KNOWN_CAPABILITIES` and must be
+     * backed by an actual `contributes.*` entry. Validated at
+     * activation time.
+     */
+    provides?: string[];
+    /**
+     * Capabilities (ADR-0004 §5) this plugin needs from some other
+     * active plugin in the same tenant (or from itself, if it both
+     * provides and requires). Each entry must be a member of
+     * `KNOWN_CAPABILITIES`.
+     */
+    requires?: string[];
+    client?: PluginEntryRef;
+    server?: PluginEntryRef;
+    contributes?: ContributesV1;
+    /**
+     * Optional declarative schema for the plugin's own config
+     * (`tenant config.plugins.<id>.config`). When present the host
+     * exposes a config form in the Plugin Manager UI; users edit
+     * fields, host writes back via `PATCH /api/plugins/:id`.
+     *
+     * Field kinds we currently support:
+     *   - boolean : checkbox
+     *   - number  : number input (with optional `min`, `max`, `step`)
+     *   - string  : single-line text input
+     *
+     * The schema is intentionally tiny — anything richer should land
+     * in a dedicated admin page contribution. The values are passed
+     * verbatim to the plugin via `PluginContext.pluginConfig`.
+     */
+    configSchema?: PluginConfigSchema;
+}
+export interface PluginConfigSchema {
+    /** Top-level fields. Order is preserved in the UI. */
+    fields: PluginConfigField[];
+}
+export type PluginConfigField = PluginConfigBoolField | PluginConfigNumberField | PluginConfigStringField | PluginConfigSecretField | PluginConfigSelectField;
+interface PluginConfigFieldBase {
+    /** Dotted path under the plugin's config object, e.g. "echo.enabled". */
+    key: string;
+    /** Short label shown next to the input. */
+    label: string;
+    /** Optional one-line help, rendered under the input. */
+    description?: string;
+    /**
+     * Optional grouping. Fields sharing the same `group.id` render
+     * inside a bordered card with `group.label` as the section
+     * header; `group.badge` (when set) renders as a coloured pill
+     * next to the label so domain concepts (e.g. "worker type") get
+     * visual emphasis. Fields without `group` keep the flat layout.
+     */
+    group?: PluginConfigFieldGroup;
+}
+export interface PluginConfigFieldGroup {
+    /** Stable id; fields sharing this id are rendered together. */
+    id: string;
+    /** Section header text. */
+    label: string;
+    /** Optional small uppercase pill rendered next to the header.
+     *  Used today to highlight worker type names. */
+    badge?: string;
+    /** Optional one-line description under the header. */
+    description?: string;
+}
+export interface PluginConfigBoolField extends PluginConfigFieldBase {
+    kind: "boolean";
+    default?: boolean;
+}
+export interface PluginConfigNumberField extends PluginConfigFieldBase {
+    kind: "number";
+    default?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Optional unit suffix shown to the right of the input ("ms", "s", etc). */
+    unit?: string;
+}
+export interface PluginConfigStringField extends PluginConfigFieldBase {
+    kind: "string";
+    default?: string;
+    placeholder?: string;
+    /** When set, render as a textarea instead of an <input>. */
+    multiline?: boolean;
+}
+/**
+ * Secret string — API key, OAuth client secret, anything the user
+ * shouldn't see in plaintext after entering. Storage rules differ
+ * from `string`:
+ *   - persisted to `<tenant>/secrets/plugin-<id>.json` (mode 0700,
+ *     already a sibling-only directory) instead of `config.json`,
+ *     so a leak of `config.json` doesn't leak credentials.
+ *   - the GET /api/plugins response REDACTS the value: clients see
+ *     `{ "<key>": { "__secret": true, "set": true|false } }` and
+ *     never the cleartext.
+ *   - PATCH semantics: passing a string sets it; passing
+ *     `{ "__secret": true, "clear": true }` removes it; omitting
+ *     the field leaves the existing value untouched. ("submit-the-
+ *     redacted-shape-back" stays a no-op, which is what the form
+ *     does on save when the user didn't touch the field.)
+ *
+ * The plugin sees the cleartext at activation time (merged into
+ * `pluginConfig` from `secrets/`) — same shape as a regular string
+ * field, no extra plumbing in the plugin code.
+ */
+export interface PluginConfigSecretField extends PluginConfigFieldBase {
+    kind: "secret";
+    /** Optional placeholder, e.g. "tvly-...". No `default`: secrets
+     *  must come from the user, not the manifest. */
+    placeholder?: string;
+}
+/**
+ * Single-choice picker. Used when the field has a small fixed set
+ * of valid values (e.g. "tavily" | "brave") — lets the form
+ * surface a labelled dropdown instead of a free-text input the
+ * user might typo into.
+ *
+ *   - `default` is the option's `value` (not its label) — same
+ *     contract as the persisted config.
+ *   - `options[].label` is the human-readable text shown in the
+ *     dropdown; `options[].value` is what's persisted.
+ */
+export interface PluginConfigSelectField extends PluginConfigFieldBase {
+    kind: "select";
+    default?: string;
+    options: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+export interface PluginEntryRef {
+    /**
+     * Module specifier resolved by the host bundle / require chain.
+     * For builtin v0 plugins this is a known package name in the server
+     * or web bundle's module graph.
+     */
+    entry: string;
+}
+export interface ContributesV1 {
+    topBarButtons?: TopBarButtonContribution[];
+    rightPanels?: RightPanelContribution[];
+    sidebarSections?: SidebarSectionContribution[];
+    /**
+     * Admin pages the plugin contributes to the chat shell's `/admin`
+     * surface (sidebar + nested route). Each entry shows up as a left-nav
+     * item under `/admin/<plugin-id>/<id>` and renders the named
+     * client component. Use this for management UIs that don't fit
+     * the right-panel form factor: full-width forms, multi-section
+     * settings pages, log viewers, etc. See ADR-0004 §12.
+     */
+    adminPages?: AdminPageContribution[];
+    /**
+     * Sandbox runtime providers (ADR-0004 §1). Each entry registers a
+     * `SandboxRunner` whose `kind` selects which agent tools the
+     * core wires up (e.g. `kind: "shell"` → `exec` / `reset_sandbox`).
+     */
+    sandboxes?: SandboxContribution[];
+    /**
+     * Agent tools the plugin contributes. The host collects every
+     * active plugin's tools each turn and registers them with the
+     * chat agent. `module` is the key in the plugin's
+     * `exports.tools` map.
+     */
+    tools?: ToolContribution[];
+    /**
+     * Dynamic *toolsets* the plugin contributes — most commonly an
+     * MCP server reflected through the SDK's `McpToolset`. Each entry
+     * names a `ToolsetProvider` exported from
+     * `exports.toolsetProviders`. The host calls
+     * `provider.listTools()` every turn so the visible tool surface
+     * can grow / shrink as upstream MCP servers come online or
+     * disappear, without re-activating the plugin.
+     */
+    toolsets?: ToolsetContribution[];
+    /**
+     * Skills (markdown how-to files) the plugin ships. Each skill is
+     * advertised to the agent by name + description; the agent calls
+     * the host's `load_skill` meta-tool to pull the body into context
+     * on demand. See ADR-0004 §11.
+     */
+    skills?: SkillContribution[];
+    /**
+     * Worker-agent seed bundles the plugin ships. On first activation
+     * for a tenant, the host copies each entry's `path` into
+     * `<tenant>/_tenant/config/workers/<id>/`. Already-existing
+     * directories are left alone, so a user edit survives plugin
+     * upgrades and a deleted seed stays deleted (mirrors the
+     * `ensureTenantConfigDefaults` semantics for skill bundles).
+     *
+     * The seed directory layout matches the runtime layout the loader
+     * expects:
+     *
+     *   <id>/
+     *     agent.json           (required: kind, modelId?, enabled, ...)
+     *     SOUL.md              (optional: system prompt)
+     *     skills/<name>/...    (optional: pre-installed skills)
+     *
+     * `<id>` becomes the worker's slug — stable, kebab-case,
+     * unique within the plugin.
+     */
+    agentSeeds?: AgentSeedContribution[];
+    /**
+     * Static system-prompt fragments injected into the main chat
+     * agent's prompt when this plugin is active for the current
+     * tenant. Use sparingly — each fragment costs context budget
+     * on every turn for every user. The right shape is a short
+     * imperative sentence or two that changes the agent's default
+     * disposition; long instructions belong in skills (which are
+     * read on demand) instead.
+     *
+     * Worker-side prompts are not affected. Only the main chat
+     * agent loads these.
+     *
+     * Example: workboard ships a fragment that nudges the main
+     * agent toward delegating non-trivial requests to the worker
+     * pool rather than doing the work in-line.
+     */
+    systemPromptFragments?: SystemPromptFragmentContribution[];
+    /**
+     * Buttons in the chat composer (left of Send). The contributed
+     * component renders inside the input row and gets a `composer`
+     * prop with `useComposer()`-equivalent capabilities (manage
+     * attachments, register draft transforms). See ADR-0003 §7.
+     */
+    composerActions?: ComposerActionContribution[];
+    /**
+     * Components that render the attachment chips/thumbnails attached
+     * to a user message. The host walks contributions in order and
+     * picks the first whose `mimePattern` matches the attachment's
+     * mime type. This is how the host stays decoupled from any
+     * particular file plugin's URL scheme. See ADR-0003 §12.
+     */
+    attachmentRenderers?: AttachmentRendererContribution[];
+    apiRoutes?: ApiRouteContribution[];
+    wsMessages?: WsMessageContribution[];
+}
+export type SandboxKind = "shell";
+export interface SandboxContribution {
+    /** Local id; surfaced as `<plugin-id>.<id>` to the world. */
+    id: string;
+    kind: SandboxKind;
+    displayName: string;
+    /** Key in the plugin's server-exports `sandboxes` map. */
+    module: string;
+}
+export interface ToolContribution {
+    /** Local id, mostly for debugging / Plugin Manager UI. */
+    id: string;
+    /** Key in the plugin's server-exports `tools` map. The tool's
+     *  user-facing name (what the model sees) lives in the tool's
+     *  pi-ai schema, not here — we don't enforce a 1:1 between this
+     *  contribution id and the schema name. */
+    module: string;
+}
+export interface ToolsetContribution {
+    /** Local id, surfaced in the admin MCP servers view + plugin
+     *  manager. */
+    id: string;
+    /** Key in the plugin's server-exports `toolsetProviders` map. */
+    module: string;
+    /** Optional human label shown in the admin MCP servers view.
+     *  Defaults to `id`. */
+    displayName?: string;
+}
+export interface SkillContribution {
+    /** Local id; surfaced as `<plugin-id>.<id>` for logging. */
+    id: string;
+    /**
+     * Path (relative to the plugin's manifest dir) to the markdown
+     * skill file. Frontmatter declares `name`, `description`, and an
+     * optional `when` predicate. Body is whatever the agent should
+     * read after `load_skill(name)`.
+     */
+    path: string;
+}
+export interface SystemPromptFragmentContribution {
+    /** Local id; surfaced as `<plugin-id>.<id>` for log lines. */
+    id: string;
+    /**
+     * The literal markdown / plain text injected into the system
+     * prompt. Wrapped automatically in a section header derived
+     * from the plugin's displayName so the agent can tell where
+     * the rule came from. Keep it tight — one or two sentences
+     * unless you really need more.
+     */
+    text: string;
+}
+export interface AgentSeedContribution {
+    /**
+     * Local slug. Becomes the directory name under
+     * `_tenant/config/workers/<id>/`. Kebab-case, must be unique
+     * within this plugin (and ideally across plugins; collisions are
+     * resolved last-writer-wins with a console warning).
+     */
+    id: string;
+    /**
+     * Path to the seed directory, relative to the plugin's manifest.
+     * The host copies the *contents* of this directory into the
+     * tenant slot — not the directory itself — so an `agent.json`
+     * sitting at `<path>/agent.json` lands at
+     * `_tenant/config/workers/<id>/agent.json`.
+     */
+    path: string;
+}
+export interface TopBarButtonContribution {
+    /** Local id; surfaced as `<plugin-id>.<id>` to the world. */
+    id: string;
+    /** lucide-react export name. */
+    icon: string;
+    tooltip?: string;
+    /** Right-panel id (also `<plugin-id>.<id>`) that this button toggles. */
+    opensPanel?: string;
+    /** Smaller order = further left. Default 100. */
+    order?: number;
+}
+export interface RightPanelContribution {
+    id: string;
+    displayName: string;
+    /** Key in the plugin's client-exports `components` map. */
+    component: string;
+}
+export interface SidebarSectionContribution {
+    id: string;
+    displayName: string;
+    component: string;
+    /** Anchor section id (`workers`, `channels`, …). Plugin sections
+     *  render after the named anchor. */
+    after?: string;
+    /** Smaller order = higher up among plugins sharing the same anchor. */
+    order?: number;
+}
+export interface ComposerActionContribution {
+    /** Local id; surfaced as `<plugin-id>.<id>` to the world. */
+    id: string;
+    /** lucide-react export name. Rendered next to the icon-only button. */
+    icon?: string;
+    tooltip?: string;
+    /** Key in the plugin's client-exports `components` map. The
+     *  component takes `ComposerActionProps`. If omitted, a built-in
+     *  icon-only button is rendered (clicking it triggers a
+     *  client-side default action via the manifest — reserved for v1). */
+    component: string;
+    /** Smaller order = further left among composer actions. Default 100. */
+    order?: number;
+}
+export interface AttachmentRendererContribution {
+    /** Local id; surfaced as `<plugin-id>.<id>` to the world. */
+    id: string;
+    /**
+     * Mime pattern this renderer handles. Three forms supported:
+     *   - exact:        `application/pdf`
+     *   - type wildcard: `image/*`
+     *   - catchall:      `*\/*`
+     * Patterns are matched in plugin/contrib order; the first match
+     * wins. Plugins should give wildcards a higher (numerically
+     * larger) `order` so exact-match contributions get a chance first.
+     */
+    mimePattern: string;
+    /** Key in the plugin's client-exports `components` map. The
+     *  component receives `AttachmentRendererProps`. */
+    component: string;
+    /** Smaller order = checked first. Default 100. */
+    order?: number;
+}
+export interface AdminPageContribution {
+    /** Local id; surfaced as `<plugin-id>.<id>` for routing/logging. */
+    id: string;
+    /** Sidebar label. */
+    displayName: string;
+    /** lucide-react export name; rendered next to the label. */
+    icon?: string;
+    /** Key in the plugin's client-exports `components` map. The
+     *  component receives `AdminPageProps`. */
+    component: string;
+    /** Smaller order = higher in the sidebar. Default 100. */
+    order?: number;
+    /** Optional sub-section title in the sidebar (e.g. "Sandbox",
+     *  "Models"). Pages with the same group render under one heading
+     *  in declaration order. */
+    group?: string;
+}
+export interface ApiRouteContribution {
+    /** HTTP verb. */
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    /** Path mounted at `/api/p/<plugin-id><path>`. Must start with `/`. */
+    path: string;
+    /** Key in the plugin's server-exports `routes` map. */
+    handler: string;
+}
+export interface WsMessageContribution {
+    /** Wire-format `type` value. Globally unique across active plugins. */
+    type: string;
+    /** Key in the plugin's server-exports `wsHandlers` map. */
+    handler: string;
+}
+export {};
+//# sourceMappingURL=manifest.d.ts.map

package/packages/plugin-sdk/dist/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"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"}

package/packages/plugin-sdk/dist/manifest.js

@@ -0,0 +1,7 @@
+// Plugin manifest types (ADR-0003 §5).
+//
+// We deliberately keep these as plain TS interfaces — no schema lib in
+// v0. Validation in `core/plugins/manifest.ts` checks the same shape at
+// runtime.
+export {};
+//# sourceMappingURL=manifest.js.map

package/packages/plugin-sdk/dist/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../src/manifest.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,EAAE;AACF,uEAAuE;AACvE,wEAAwE;AACxE,WAAW"}