@tianshu-ai/tianshu 0.3.0

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

@@ -0,0 +1,486 @@
+import type { Request, Response } from "express";
+import type { WebSocket } from "ws";
+import type { CapabilityName } from "./capabilities.js";
+import type { SandboxKind } from "./manifest.js";
+import type { ToolsetProvider } from "./mcp-toolset.js";
+/** Tenant-scoped context handed to every plugin's `activate(ctx)`. */
+export interface PluginContext {
+    pluginId: string;
+    tenantId: string;
+    /**
+     * The opened tenant SQLite handle. Same instance the core uses, so
+     * plugins must not call `close()` on it.
+     */
+    db: TenantDbHandle;
+    /** Resolved + merged tenant config (subset). */
+    tenantConfig: ResolvedConfigShape;
+    /** @deprecated Use `tenantConfig`. Removed in a future SDK version. */
+    config: ResolvedConfigShape;
+    /** Bound logger: prefixes [plugin:<id>] [tenant:<id>]. */
+    log: PluginLogger;
+    /** Absolute path to `<tenant>/workspace`. */
+    workspaceDir: string;
+    /** Absolute path to a user's per-tenant home, i.e.
+     *  `<tenant>/workspace/users/<userId>`. Plugins resolve this at
+     *  request time using `req.ctx.userId` (set by host middleware). */
+    userHomeDir(userId: string): string;
+    /** Send a WS message to every socket currently connected for this tenant. */
+    broadcast(type: string, payload: unknown): void;
+    /**
+     * Capability registry handle (ADR-0004 §8). Lets a plugin look up
+     * other plugins' provided capabilities. By the time `activate()` is
+     * called, every capability listed in this plugin's `requires[]` is
+     * already registered. Capabilities this plugin itself provides are
+     * **not** yet registered — see ADR-0004 §8 (single-phase activation).
+     */
+    capabilities: CapabilityHandle;
+    /**
+     * Per-plugin opaque config from `<tenant>/config.json` →
+     * `plugins[<id>].config`. Host does not interpret it; plugins
+     * cast/parse as needed. Empty object if not configured.
+     */
+    pluginConfig: Record<string, unknown>;
+}
+/**
+ * Minimal shape we need from a `better-sqlite3` Database, declared
+ * structurally so the SDK doesn't have to depend on better-sqlite3.
+ */
+export interface TenantDbHandle {
+    prepare<P extends unknown[] = unknown[], R = unknown>(sql: string): {
+        run(...params: P): unknown;
+        get(...params: P): R | undefined;
+        all(...params: P): R[];
+    };
+    exec(sql: string): unknown;
+}
+/**
+ * Subset of ResolvedConfig that plugins are allowed to read. Kept
+ * minimal — plugins should not depend on the full `@tianshu/server`
+ * type. New surface gets exposed here on demand.
+ */
+export interface ResolvedConfigShape {
+    defaultModel?: string;
+    branding?: {
+        name?: string;
+        emoji?: string;
+    };
+}
+export interface PluginLogger {
+    info(msg: string, meta?: Record<string, unknown>): void;
+    warn(msg: string, meta?: Record<string, unknown>): void;
+    error(msg: string, meta?: Record<string, unknown>): void;
+}
+export type PluginRouteHandler = (req: Request, res: Response) => void | Promise<void>;
+export type PluginWsHandler = (msg: {
+    type: string;
+} & Record<string, unknown>, socket: WebSocket, ctx: PluginContext) => void | Promise<void>;
+export interface PluginServerExports {
+    routes?: Record<string, PluginRouteHandler>;
+    wsHandlers?: Record<string, PluginWsHandler>;
+    /**
+     * Ready-to-use sandbox runners keyed by the `module` string used
+     * in `manifest.contributes.sandboxes[].module`. The plugin's
+     * `activate(ctx)` is responsible for constructing each runner
+     * (typically in a small "facade" that picks between a real
+     * runtime and a nullable fallback) and exposing it here. The host
+     * picks the runner up by key and registers it under the matching
+     * `sandbox.<kind>` capability.
+     *
+     * The `SandboxModule` type below is exported for plugins that
+     * want to factor their runner construction into a `start(ctx) =>
+     * SandboxRunner` shape, but the host never invokes `start()`
+     * itself — plugins do that inside `activate()`.
+     */
+    sandboxes?: Record<string, SandboxRunner>;
+    /**
+     * Per-task sandbox lifecycle manager (`sandbox.taskPool`
+     * capability). The host registers it under that capability so
+     * other plugins (today: workboard) can drive task acquire/
+     * release/destroy.
+     *
+     * Distinct from `sandboxes[]` because a task pool is not a
+     * single SandboxRunner; it is a manager that creates per-task
+     * runners on demand. Plugins that don't manage per-task
+     * sandboxes (the common case) leave this undefined.
+     */
+    taskSandboxPool?: TaskSandboxPool;
+    /**
+     * Agent tools the plugin contributes. Keys must match the
+     * `module` strings declared in `manifest.contributes.tools[]`.
+     * The host collects every active plugin's tools each agent turn
+     * and merges them with the core tool set (fs read/write/etc.).
+     *
+     * A tool's `available()` (if present) gates registration on a
+     * per-turn basis — use this for status-aware tools whose backing
+     * runner may not be ready yet.
+     */
+    tools?: Record<string, AgentTool>;
+    /**
+     * Dynamic tool *providers* whose tool list can change at runtime.
+     * Today's only built-in implementation is `McpToolset`, which
+     * reflects an upstream MCP server's `tools/list` into AgentTools
+     * on each refresh — see `mcp-toolset.ts`. Keys must match the
+     * `module` strings declared in `manifest.contributes.toolsets[]`.
+     *
+     * The host calls `provider.listTools()` every time it builds the
+     * per-turn tool list, so the surface area can grow / shrink as
+     * MCP servers come and go without the plugin having to re-run
+     * `activate()`. Failures inside a provider are visible through
+     * the global MCP admin page (powered by `provider.snapshot?.()`).
+     */
+    toolsetProviders?: Record<string, ToolsetProvider>;
+}
+export interface CapabilityHandle {
+    /** Get a registered capability's value, or undefined if no provider. */
+    get<T = unknown>(name: CapabilityName): T | undefined;
+    /** Cheaper than `get()` when the caller doesn't need the value. */
+    has(name: CapabilityName): boolean;
+    /**
+     * Subscribe to lifecycle events for one capability. Useful when a
+     * plugin or the agent loop wants to react when a provider comes or
+     * goes mid-process (registry invalidation, plugin re-enabled, ...).
+     * Returns an unsubscribe function.
+     */
+    on(name: CapabilityName, ev: "registered" | "unregistered", fn: () => void): () => void;
+}
+/**
+ * Per-call context handed to an agent tool's `execute()`. Lets the
+ * tool reach back into the tenant capability registry, the user's
+ * home dir, and a small log surface without re-deriving them. Host
+ * fills this in on every tool invocation.
+ */
+export interface AgentToolContext {
+    pluginId: string;
+    tenantId: string;
+    userId: string;
+    /** Read-only capability lookup. Subset of CapabilityHandle
+     *  (no event subscription) because tool execution is
+     *  request-scoped — if a capability flips during a turn, the
+     *  agent loop will pick that up next turn via toolsForTenant. */
+    capabilities: ReadOnlyCapabilityHandle;
+    /** Per-user workspace dir on the host filesystem. */
+    userHomeDir: string;
+    /** Tenant root dir (host filesystem). Plugins that need to write
+     *  to `<tenant>/_tenant/config/...` use this; most tools don't. */
+    tenantHomeDir: string;
+    /**
+     * Agent identity inside the tenant.
+     *
+     *   - { kind: "main" }
+     *     The chat-shell agent the user is talking to. Default if a
+     *     plugin tool is invoked outside any agent loop (e.g. from a
+     *     route handler).
+     *   - { kind: "worker", workerKind: "<id>" }
+     *     A worker pool run; `workerKind` is the worker_agent kind
+     *     id (e.g. "llm", "echo").
+     *
+     * Tools that touch shared tenant config (skills, future SOUL/
+     * MEMORY surfaces) use this to enforce a write boundary: main
+     * may write to `_tenant/config/main/...` and `_tenant/config/`;
+     * workers may only write to `_tenant/config/workers/<kind>/...`.
+     * Reads are not gated by this field.
+     *
+     * Optional for backwards compatibility — missing means "main".
+     */
+    agentScope?: {
+        kind: "main";
+    } | {
+        kind: "worker";
+        workerKind: string;
+        /** Worker's filesystem slug (matches the directory name
+         *  under `_tenant/config/workers/<slug>/`). When unset the
+         *  worker is running with no fs presence — falling back to
+         *  the legacy DB-only path. Used by the tenant_config_*
+         *  tools to scope writes to this worker's own bundle. */
+        slug?: string;
+    };
+    log: PluginLogger;
+    /**
+     * Id of the chat / worker session the LLM that called this tool
+     * is running in. Plugins use it to attribute side-effects back
+     * to the asking session (e.g. workboard's task_create stamps
+     * `tasks.parent_session_id` so the worker pool can later notify
+     * this session when the task finishes).
+     *
+     * Optional: tools invoked outside an LLM session (e.g. internal
+     * scheduled jobs) won't have one.
+     */
+    sessionId?: string;
+    /**
+     * Workboard task id when this tool call is driven by a worker
+     * pool run. Lets per-task tools scope their resources to a
+     * single task lifecycle — e.g. microsandbox routes `exec` calls
+     * for a worker session into a dedicated per-task sandbox that
+     * gets stopped when the task terminates.
+     *
+     * Absent for chat sessions and ad-hoc tool invocations.
+     */
+    taskId?: string;
+    /**
+     * Cancellation signal for the current run. The host wires this
+     * from the agent loop's inner abort controller, so a watchdog
+     * timeout, an external `task_abort`, or any other reason the
+     * loop unwinds will fire this signal. Tools that do long-running
+     * work (`exec`, MCP calls, network fetches) SHOULD listen and
+     * bail early; tools that are inherently quick can ignore it.
+     *
+     * Optional for backwards compatibility — plugins built against
+     * older SDK versions never see this field, and the host
+     * tolerates that.
+     */
+    signal?: AbortSignal;
+}
+/** Lookup-only subset of CapabilityHandle (no `on()`). */
+export interface ReadOnlyCapabilityHandle {
+    get<T = unknown>(name: CapabilityName): T | undefined;
+    has(name: CapabilityName): boolean;
+}
+/**
+ * Canonical result shape an agent tool should return. Two extra
+ * fields beyond `{ ok, text }` are recognised:
+ * - `data`: structured payload the host JSON-encodes into the chat
+ *   log alongside `text`, so the agent sees both the human-readable
+ *   summary and the structured details.
+ * - any other field: passed through verbatim for plugins that want
+ *   to attach custom metadata (e.g. `exit_code`, `duration_ms`).
+ *
+ * Tools MAY return arbitrary JSON-serialisable values; the host
+ * normalises them to `{ ok, text }` before they reach the LLM.
+ * Returning this canonical shape directly is preferred because
+ * the agent sees a consistent surface across plugins.
+ *
+ * Use the {@link okResult} / {@link errorResult} helpers in
+ * `tools/result.js` (or hand-roll) to build these.
+ */
+export interface ToolResult {
+    /** True iff the tool semantically succeeded. The host renders the
+     *  tool-call chip green when ok, red when not. */
+    ok: boolean;
+    /** Human-readable summary the agent sees. Keep it short — model
+     *  context is precious. Long output should go to a file via
+     *  another tool, not into `text`. */
+    text: string;
+    /** Optional structured payload preserved verbatim. */
+    data?: unknown;
+    /** Plugin-defined extras. Allowed but discouraged. */
+    [key: string]: unknown;
+}
+/**
+ * A schema + executor pair that becomes an agent tool. The host
+ * collects these from every active plugin via
+ * `exports.tools[<module-key>]`, gates each one through
+ * `available()`, then registers the surviving schemas with the
+ * agent loop.
+ *
+ * Prefer returning a {@link ToolResult} from `execute()`. If you
+ * return any other JSON-serialisable value, the host JSON-encodes
+ * it into `text` and best-effort-derives `ok`.
+ */
+export interface AgentTool {
+    /** pi-ai Tool schema. Name is what the model sees. */
+    schema: import("@earendil-works/pi-ai").Tool;
+    /** Optional per-turn gate. Return false to hide the tool this
+     *  turn (e.g. when the backing capability is in `state: error`).
+     *  Default true. */
+    available?(ctx: AgentToolContext): boolean | Promise<boolean>;
+    /** Run the tool with the model-supplied args. */
+    execute(args: Record<string, unknown>, ctx: AgentToolContext): ToolResult | unknown | Promise<ToolResult | unknown>;
+}
+/** Build an `ok=true` ToolResult. Optional `data` payload preserved. */
+export declare function okResult(text: string, data?: unknown): ToolResult;
+/** Build an `ok=false` ToolResult. Optional `data` payload preserved. */
+export declare function errorResult(text: string, data?: unknown): ToolResult;
+/**
+ * Optional convenience interface for plugins that want to factor
+ * runner construction out of `activate()`. The host does not call
+ * `start()` itself — plugins call it from inside `activate()` and
+ * expose the returned runner via `exports.sandboxes[<key>]`.
+ */
+export interface SandboxModule {
+    start(ctx: PluginContext): Promise<SandboxRunner>;
+}
+export interface SandboxRunner {
+    /** Stable id; equals `<plugin-id>.<contribution-id>`. */
+    readonly id: string;
+    readonly kind: SandboxKind;
+    exec(req: ExecRequest): Promise<ExecResult>;
+    readFile(relPath: string): Promise<string>;
+    writeFile(relPath: string, content: string): Promise<void>;
+    /** Host-side absolute path to this tenant's workspace dir. */
+    workspacePath(): string;
+    /** Drop in-memory state and re-init. Triggered only by an admin
+     *  Reset action or by the agent's `reset_sandbox` tool. The host
+     *  never auto-resets. */
+    reset(): Promise<void>;
+    /** Tear down. Called on tenant DB pool eviction or plugin
+     *  deactivation. Must be idempotent. */
+    shutdown(): Promise<void>;
+    /** Snapshot for the status panel + `GET /api/p/<id>/status`. */
+    status(): Promise<SandboxStatus>;
+    /** If this runner's plugin also provides `browser.cdp`, the
+     *  sidecar is exposed here so the host can register it under the
+     *  capability without a second module entry. Otherwise undefined. */
+    readonly browser?: BrowserSidecar;
+}
+export interface ExecRequest {
+    /** Shell command. Equivalent to `bash -c <command>` in the guest. */
+    command: string;
+    /** Working directory inside the guest. Default: `/workspace`. */
+    workdir?: string;
+    /** Override timeout in ms. Default plugin-defined; the host caps
+     *  this at 30 min when wiring up the agent's `exec` tool. */
+    timeoutMs?: number;
+    /** Tenant-scoped user id whose context the command should run in.
+     *  Runners use it to populate `$USER`, `$LOGNAME`, `$HOME` and an
+     *  optional `$MSB_USER_ID` so shell scripts inside the guest see a
+     *  proper user context even though the guest process itself runs
+     *  as root (microsandbox has no user namespacing in v0). When
+     *  omitted, the command runs with empty `$USER` and `$HOME=/root`,
+     *  matching the SDK's default. */
+    userId?: string;
+    /** Workboard task id when this exec belongs to a per-task run.
+     *  Routers (e.g. microsandbox) dispatch the call into the task's
+     *  dedicated sandbox; absent calls go to the long-lived runner. */
+    taskId?: string;
+    /** Chat / worker session id. Routers fall back to this when
+     *  `taskId` is absent so chat sessions linked to a task via
+     *  `TaskSandboxPool.bindSession` still land in the right
+     *  per-task sandbox. */
+    sessionId?: string;
+    /** Optional cancellation signal. Runners SHOULD watch this and
+     *  abort the in-flight exec (best-effort SIGKILL of the guest
+     *  process) so callers can interrupt a runaway command without
+     *  waiting for the timeout. The host wires this from the agent
+     *  loop's inner abort controller, so a `task_abort` (or any
+     *  other source that aborts the run) propagates straight down
+     *  to the guest. */
+    signal?: AbortSignal;
+}
+export interface ExecResult {
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+    /** Wall time in ms. */
+    durationMs: number;
+    /** True iff the command was killed by timeout. */
+    timedOut: boolean;
+    /** True iff the command was killed by the caller's abort signal
+     *  rather than running to completion or hitting the timeout.
+     *  Optional for backwards compatibility. */
+    aborted?: boolean;
+}
+export type SandboxState = "starting" | "ready" | "running" | "error" | "stopped";
+export interface SandboxStatus {
+    state: SandboxState;
+    /** Wall time the runner has been in its current incarnation. */
+    uptimeMs: number;
+    lastError?: string;
+    /** Plugin-specific extras (image, idle countdown, sidecar status, …). */
+    meta?: Record<string, unknown>;
+}
+/**
+ * Per-task sandbox lifecycle manager. Registered by the
+ * microsandbox plugin under the `sandbox.taskPool` capability;
+ * workboard's worker pool calls into it at task pickup / end /
+ * delete to drive the per-task microVM lifecycle.
+ *
+ * The actual `exec` routing happens transparently inside the
+ * SandboxRunner registered under `sandbox.shell`: when a tool
+ * call carries `ctx.taskId`, the runner forwards it to the pool
+ * which dispatches into the right per-task sandbox.
+ */
+export interface TaskSandboxPool {
+    /**
+     * Block until a sandbox exists for `taskId` and is ready to
+     * receive `exec` calls. Idempotent — a no-op when the sandbox
+     * is already running. When the sandbox was previously stopped
+     * (e.g. an earlier attempt terminated), this resumes it so the
+     * filesystem state from the prior run is preserved.
+     */
+    acquireTask(taskId: string, sessionId?: string): Promise<void>;
+    /**
+     * Stop (but do not remove) the sandbox bound to `taskId`. The
+     * disk image is preserved so a follow-up `acquireTask` resumes
+     * the same environment. Safe to call when the sandbox is
+     * already stopped or doesn't exist.
+     *
+     * Implementations SHOULD return promptly; do the actual stop
+     * out-of-band so the worker pool isn't blocked on next pickup.
+     */
+    releaseTask(taskId: string): Promise<void> | void;
+    /**
+     * Stop AND remove the sandbox bound to `taskId`. Called when a
+     * task is permanently deleted; reclaims disk. Safe to call when
+     * no such sandbox exists.
+     */
+    destroyTask(taskId: string): Promise<void>;
+    /**
+     * Bind a chat / worker session id to a `taskId` so the runner
+     * can route `exec` calls keyed by `ctx.sessionId` back to the
+     * task sandbox. Called from the worker's `onSessionStart` hook.
+     */
+    bindSession(sessionId: string, taskId: string): void;
+}
+export interface BrowserSidecar {
+    /** Host port forwarded to chromium CDP (9222 inside guest). */
+    cdpHostPort(): number | undefined;
+    /** Host port forwarded to Playwright MCP (3200 inside guest). */
+    mcpHostPort(): number | undefined;
+    /** Host port forwarded to noVNC (6080 inside guest). */
+    vncHostPort(): number | undefined;
+    /** Set by the BrowserPanel ResizeObserver; read by the agent's
+     *  browser tool to re-apply page.setViewportSize() after navigation. */
+    setLastViewport(v: {
+        width: number;
+        height: number;
+    }): void;
+    getLastViewport(): {
+        width: number;
+        height: number;
+    } | undefined;
+    /** Restart chromium + playwright-mcp without rebuilding the whole
+     *  sandbox. Returns true on success. */
+    restart(): Promise<boolean>;
+    /**
+     * Probe the browser stack and report whether it answers a CDP
+     * discovery request right now. The implementation does
+     * `GET http://127.0.0.1:<cdpHostPort>/json/version` with a
+     * short timeout and translates the outcome into a single
+     * status object the agent can act on:
+     *
+     *   - ok=true: chromium answered, latencyMs is the round-trip,
+     *     `browser`/`webSocketDebuggerUrl` echoed for diagnostics.
+     *   - ok=false: cdpHostPort isn't set (sidecar has no chromium),
+     *     or the probe timed out / 5xx'd / connection-reset. The
+     *     `error` and `suggestion` strings are agent-readable so
+     *     the tool result can pass them through verbatim.
+     *
+     * Cheap (~1-5ms when healthy). Safe to call from a tool result
+     * post-hook on every browser_* call without serious cost.
+     */
+    health(): Promise<BrowserSidecarHealth>;
+}
+export interface BrowserSidecarHealth {
+    ok: boolean;
+    latencyMs: number;
+    /** Browser version string from /json/version when the probe
+     *  succeeded; absent on failure. */
+    browser?: string;
+    /** Failure reason when ok=false; absent on success. */
+    error?: string;
+    /** Agent-actionable next step when ok=false. Examples:
+     *    "call browser_restart to re-spawn chromium + Playwright MCP"
+     *    "the sandbox itself is unhealthy; ask the orchestrator to reset_sandbox"
+     *  Absent on success. */
+    suggestion?: string;
+    /** Host CDP port at probe time. Useful for diagnostics when
+     *  the port forward itself moved (e.g. after reset_sandbox). */
+    cdpHostPort?: number;
+}
+/** A server-side plugin module exports `activate` (required) and
+ *  optional `deactivate`. */
+export interface PluginServerModule {
+    activate(ctx: PluginContext): Promise<PluginServerExports> | PluginServerExports;
+    deactivate?(): Promise<void> | void;
+}
+//# sourceMappingURL=server.d.ts.map

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

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

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

@@ -0,0 +1,10 @@
+// Server-side plugin runtime contract (ADR-0003 §6, ADR-0004 §2/§8).
+/** Build an `ok=true` ToolResult. Optional `data` payload preserved. */
+export function okResult(text, data) {
+    return data === undefined ? { ok: true, text } : { ok: true, text, data };
+}
+/** Build an `ok=false` ToolResult. Optional `data` payload preserved. */
+export function errorResult(text, data) {
+    return data === undefined ? { ok: false, text } : { ok: false, text, data };
+}
+//# sourceMappingURL=server.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,qEAAqE;AA2TrE,wEAAwE;AACxE,MAAM,UAAU,QAAQ,CAAC,IAAY,EAAE,IAAc;IACnD,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC5E,CAAC;AAED,yEAAyE;AACzE,MAAM,UAAU,WAAW,CAAC,IAAY,EAAE,IAAc;IACtD,OAAO,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC;AAC9E,CAAC"}

package/packages/plugin-sdk/dist/session-inbox.d.ts

@@ -0,0 +1,56 @@
+/** Kinds of inbox messages the host knows how to render.
+ *
+ *  - `task_done` — worker called task_complete cleanly.
+ *  - `task_intervention_required` (008+) — worker run failed,
+ *    timed out, or hit watchdog; main agent decides next step
+ *    (continue / retry_fresh / extend_timeout / abort).
+ *  - `task_stalled` — legacy alias kept for forward compat with
+ *    pre-008 senders. Host renderer treats it identically to
+ *    `task_intervention_required`.
+ *  - `system_note` — generic kernel/admin note.
+ */
+export type InboxMessageKind = "task_done" | "task_intervention_required" | "task_stalled" | "system_note";
+export interface InboxMessage {
+    /**
+     * Symbolic kind drives the rendered prefix the agent sees, e.g.
+     * "[Task done] T1 — summary…". Unknown kinds fall back to plain
+     * `system_note`.
+     */
+    kind: InboxMessageKind;
+    /**
+     * Free-form text. Rendered verbatim under the kind-specific
+     * prefix. Plain UTF-8; markdown is fine, the agent's renderer
+     * will pick it up.
+     */
+    text: string;
+    /**
+     * Optional structured metadata the host stores alongside the
+     * message. Not surfaced to the agent — debugging only.
+     */
+    meta?: Record<string, unknown>;
+}
+export interface SessionInboxCapability {
+    /**
+     * Enqueue a message for the given session.
+     *
+     * Behaviour:
+     *   - If the target session has an active harness instance in
+     *     this host process, the message is forwarded via
+     *     `harness.followUp(...)` so the running agent picks it up
+     *     mid-turn (or at the next turn if it's between provider
+     *     calls). The DB row is marked delivered.
+     *   - Otherwise the message persists with status='pending';
+     *     the next user-driven prompt on that session flushes it
+     *     as a system-note prefix before passing the user text
+     *     to the LLM.
+     *
+     * Errors thrown from this method MUST NOT bubble into the
+     * caller's tool execution path — implementations log and
+     * swallow. A failing inbox is a degraded mode, not a fatal one.
+     *
+     * Returns the inbox row id so callers can correlate later
+     * delivery events to their origin tool call.
+     */
+    enqueue(targetSessionId: string, message: InboxMessage): Promise<string>;
+}
+//# sourceMappingURL=session-inbox.d.ts.map

package/packages/plugin-sdk/dist/session-inbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-inbox.d.ts","sourceRoot":"","sources":["../src/session-inbox.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;GAUG;AACH,MAAM,MAAM,gBAAgB,GACxB,WAAW,GACX,4BAA4B,GAC5B,cAAc,GACd,aAAa,CAAC;AAElB,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,IAAI,EAAE,gBAAgB,CAAC;IACvB;;;;OAIG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED,MAAM,WAAW,sBAAsB;IACrC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,OAAO,CAAC,eAAe,EAAE,MAAM,EAAE,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC1E"}

package/packages/plugin-sdk/dist/session-inbox.js

@@ -0,0 +1,12 @@
+// Capability-side type for `host.sessionInbox`.
+//
+// The host registers an implementation; plugins fetch it through
+// `ctx.capabilities.get<SessionInboxCapability>("host.sessionInbox")`.
+//
+// Why this lives in the SDK and not in @tianshu/server:
+//   plugins shouldn't take a server-package dep just to enqueue an
+//   inbox message. Mirror the shape here, document the contract,
+//   and let the host implementation match it structurally. Same
+//   pattern as `AgentLoopRunner`.
+export {};
+//# sourceMappingURL=session-inbox.js.map

package/packages/plugin-sdk/dist/session-inbox.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-inbox.js","sourceRoot":"","sources":["../src/session-inbox.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,EAAE;AACF,iEAAiE;AACjE,uEAAuE;AACvE,EAAE;AACF,wDAAwD;AACxD,mEAAmE;AACnE,iEAAiE;AACjE,gEAAgE;AAChE,kCAAkC"}

package/packages/plugin-sdk/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@tianshu/plugin-sdk",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Plugin authoring SDK for Tianshu (server + client types).",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client.d.ts",
+      "default": "./dist/client.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run --passWithNoTests"
+  },
+  "devDependencies": {
+    "@types/node": "^25.9.1",
+    "@types/react": "^19.2.17",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.6"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0"
+  }
+}

package/packages/server/builtinConfig/plugins/README.md

@@ -0,0 +1 @@
+(empty in v0; PR #32 will populate this with files / browser / task-board / calendar stubs)