@sisylabs/kernel 0.1.0

package/README.md

@@ -0,0 +1,80 @@
+# @sisylabs/kernel
+
+Shared plugin contracts for the [Sisyphus](https://github.com/Devilsparta/Sisyphus) AI-native VSCode platform. Every Sisyphus plugin imports types from here; that's the whole point of the package.
+
+## Install
+
+```bash
+npm install --save-dev @sisylabs/kernel
+```
+
+Most of what you'll use are `import type` declarations — the package emits a tiny amount of runtime code only for the UI registries (`@sisylabs/kernel/ui`), and `KernelEvents` constants.
+
+## Authoring a plugin
+
+```typescript
+import type {
+  SisyphusPlugin,
+  AgentImpl,
+  SkillDescriptor,
+  SkillHandler,
+} from '@sisylabs/kernel';
+
+const myAgent: AgentImpl = {
+  descriptor: {
+    id: 'my-plugin.agent.hello',
+    displayName: 'Hello',
+    description: 'A friendly greeter',
+    spawnHint: 'when the user says hi',
+    triggerKeywords: ['hi', 'hello'],
+  },
+  async run(userMessage, ctx) {
+    ctx.emit({ type: 'token', text: `Hi! You said: ${userMessage}` });
+    ctx.emit({ type: 'done', reason: 'stop' });
+  },
+};
+
+const plugin: SisyphusPlugin = {
+  manifest: {
+    id: 'my-plugin',
+    displayName: 'My Plugin',
+    version: '0.1.0',
+    contributes: { agents: [myAgent.descriptor] },
+  },
+  agents: [myAgent],
+};
+
+export default plugin;
+```
+
+Compile to ESM with esbuild or tsc; ship `dist/index.mjs` as your daemon entry. The Sisyphus daemon SEA binary has no TypeScript loader, so prod plugins must be pre-compiled JS.
+
+`package.json` must include `"keywords": ["sisyphus-plugin"]` to show up in npm registry search, plus a `sisyphus` block:
+
+```json
+{
+  "keywords": ["sisyphus-plugin"],
+  "sisyphus": {
+    "id": "my-plugin",
+    "version": "0.1.0",
+    "contributes": {
+      "agents": ["my-plugin.agent.hello"]
+    }
+  }
+}
+```
+
+## What's exported
+
+- **`@sisylabs/kernel`** — all types: `SisyphusPlugin`, `PluginManifest`, `AgentImpl`, `AgentDescriptor`, `AgentRunContext`, `AgentEvent`, `SkillDescriptor`, `SkillHandler`, `ViewDescriptor`, `CardDescriptor`, `CardInstance`, `PluginContext`, `PluginStorage`, `RegistryAPI`, `Disposable`, `ChatMessage`, plus `KernelEvents` constants and `IPCMessage` envelopes.
+- **`@sisylabs/kernel/ui`** — browser-only runtime helpers your plugin's `./ui` entry uses to register views, card renderers, and React context providers: `registerView` / `registerCardRenderer` / `registerProvider` (and their list / get / dispose siblings).
+
+## Plugin RPC protocol
+
+If you're curious how plugins talk to the daemon — they don't share the daemon's process. Each activated plugin runs as its own child process and talks JSON-RPC over stdio. Full protocol: see `docs/plugin-rpc.md` in the [main repo](https://github.com/Devilsparta/Sisyphus/blob/main/docs/plugin-rpc.md).
+
+You don't have to think about the wire format though — the daemon does the marshalling and hands your code the same `ctx` it always had.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,313 @@
+/**
+ * @sisylabs/kernel — shared plugin contracts.
+ *
+ * Single source of truth for daemon ↔ UI ↔ plugin types.
+ *
+ * M2 architecture: multi-agent. The kernel hosts a Router that picks among
+ * agents contributed by plugins. Each agent runs its own LLM call and streams
+ * events directly to the UI (transparent pass-through through the daemon).
+ * Plugins describe when their agent should be spawned via `spawnHint`.
+ *
+ * See wiki: concepts/sisyphus-plugin-architecture.md
+ */
+export type Region = 'activity-bar' | 'side' | 'main' | 'bottom';
+/**
+ * A view is a unit rendered into a Panel Layout region.
+ * Metadata travels through the IPC; the renderer (React component / iframe /
+ * web component) lives on the UI side and is resolved by id.
+ */
+export interface ViewDescriptor {
+    /** Namespace-prefixed id, e.g. "plugin-base.view.canvas". */
+    id: string;
+    region: Region;
+    title: string;
+    /** Optional icon identifier (lucide name or URI). */
+    icon?: string;
+    defaultVisible?: boolean;
+}
+export interface CardDescriptor {
+    /** Namespace-prefixed type, e.g. "plugin-base.card.jsx". */
+    type: string;
+}
+export interface CardInstance {
+    type: string;
+    payload: unknown;
+    meta?: {
+        id?: string;
+        createdAt?: number;
+    };
+}
+export interface OpenAIToolSchema {
+    type: 'function';
+    function: {
+        name: string;
+        description?: string;
+        parameters?: Record<string, unknown>;
+    };
+}
+export interface SkillDescriptor {
+    /** Namespace-prefixed id, e.g. "plugin-base.skill.run-shell". */
+    id: string;
+    schema: OpenAIToolSchema;
+}
+export type SkillHandler = (args: Record<string, unknown>, ctx: SkillContext) => Promise<unknown>;
+export interface SkillContext {
+    conversationId: string;
+}
+/**
+ * Metadata describing an agent. The router uses `spawnHint` (a short natural-
+ * language clause like "use when the user wants to build a React UI") to pick
+ * between agents when multiple are registered.
+ */
+export interface AgentDescriptor {
+    /** Namespace-prefixed id, e.g. "plugin-base.agent.react-designer". */
+    id: string;
+    displayName: string;
+    /** Short user-facing description shown in the UI. */
+    description: string;
+    /**
+     * Router hint: when should this agent be spawned? Read by the router (and
+     * eventually fed to an LLM router prompt in M4+) and by the UI to explain
+     * available capabilities.
+     */
+    spawnHint: string;
+    /**
+     * Optional explicit keywords the router uses for cheap deterministic
+     * matching (M3 strategy). Higher precision than parsing the prose
+     * spawnHint. M4+ will treat these as bias signals layered atop an LLM
+     * router.
+     */
+    triggerKeywords?: string[];
+    /**
+     * Tie-breaker / fan-out ordering signal (M14).
+     * Higher = preferred. When the router fan-outs across multiple agents
+     * (or chooses among tied candidates), it picks by descending priority.
+     * Default 0 when omitted.
+     */
+    priority?: number;
+}
+/**
+ * Streaming events an agent emits during a run. They pass-through the daemon
+ * to the UI without router interpretation; the router only observes `done`
+ * for completion / retry decisions.
+ *
+ * `source` is injected by the router at emit time (agents shouldn't set it
+ * themselves); it identifies which agent produced the event. Vital for
+ * fan-out / spawnAgent traces so the UI can route events to the right cell.
+ */
+interface EventBase {
+    source?: string;
+}
+export type AgentEvent = (EventBase & {
+    type: 'token';
+    text: string;
+}) | (EventBase & {
+    type: 'reasoning';
+    text: string;
+}) | (EventBase & {
+    type: 'card';
+    card: CardInstance;
+}) | (EventBase & {
+    type: 'tool_call';
+    id: string;
+    skill: string;
+    args: Record<string, unknown>;
+}) | (EventBase & {
+    type: 'tool_result';
+    id: string;
+    result?: unknown;
+    error?: string;
+}) | (EventBase & {
+    type: 'done';
+    reason: 'stop' | 'error' | 'cancelled';
+    error?: string;
+});
+/**
+ * Context passed to an agent's `run`. The `emit` callback funnels events back
+ * through the daemon to the UI; `signal` is the abort signal the router (or
+ * the user) can fire to cancel a long-running agent.
+ */
+export interface AgentRunContext {
+    conversationId: string;
+    history: ChatMessage[];
+    emit: (event: AgentEvent) => void;
+    signal: AbortSignal;
+    /**
+     * Invoke a registered skill by id. The daemon dispatches to whichever
+     * plugin owns the skill handler. Agents should also `emit` matching
+     * `tool_call` / `tool_result` events so the UI can show the invocation
+     * trace; the platform does NOT emit those events automatically (the agent
+     * may choose to call a skill silently).
+     */
+    invokeSkill: (id: string, args: Record<string, unknown>) => Promise<unknown>;
+    /**
+     * Snapshot of every skill currently registered with the daemon. Agents
+     * use this to build the `tools` array for an LLM tool-calling call:
+     * each skill's `schema` is already OpenAI tools format.
+     *
+     * Note: OpenAI's function name pattern disallows '.', so skill.schema
+     * .function.name will not be the namespaced skill.id — the agent must
+     * keep its own name→id map when dispatching the LLM's tool_calls.
+     */
+    querySkills: () => SkillDescriptor[];
+    /**
+     * Spawn another agent as a sub-task (M14). The sub-agent's events stream
+     * through to the UI tagged with the sub-agent's id as `source`. Awaits
+     * the sub-agent to completion; its `done` is forwarded but does NOT end
+     * the parent's run — the parent must still emit its own `done`.
+     *
+     * The same skill-ACL applies to the sub-agent (it can only invoke its
+     * own plugin's skills + whatever its manifest declares).
+     */
+    spawnAgent: (agentId: string, userMessage: string) => Promise<void>;
+}
+/**
+ * A plugin-provided agent implementation. The daemon registers these and the
+ * router routes user messages to whichever one matches the situation.
+ *
+ * Contract: `run` MUST emit a final `{type:'done'}` event so the router knows
+ * the agent has completed (and can fire retries / handle timeouts). Failing
+ * to emit `done` leaves the conversation in an indeterminate state.
+ */
+export interface AgentImpl {
+    descriptor: AgentDescriptor;
+    run(userMessage: string, ctx: AgentRunContext): Promise<void>;
+}
+export interface PluginManifest {
+    /** Plugin id; used as namespace prefix for all contributed ids. */
+    id: string;
+    displayName?: string;
+    version: string;
+    /** Other plugin ids this one depends on. Daemon load order is topo-sorted. */
+    dependencies?: string[];
+    contributes?: {
+        views?: ViewDescriptor[];
+        cards?: CardDescriptor[];
+        skills?: SkillDescriptor[];
+        agents?: AgentDescriptor[];
+    };
+    /**
+     * Cross-plugin dependencies the daemon will gate at invocation time.
+     * By default a plugin's agents can only invoke skills under their own
+     * namespace; to call another plugin's skill the id must be listed here.
+     *
+     * Cross-plugin view/card use is mediated by registry queries (already
+     * shared) so doesn't need a declaration. Skills are different because
+     * they're invocable side-effects.
+     */
+    requires?: {
+        skills?: string[];
+    };
+    /**
+     * Path (relative to the plugin's package.json) of a browser-loadable
+     * ESM bundle exporting the plugin's UI surface (views, cardRenderers,
+     * providers). The daemon serves this file at
+     * GET /api/plugins/<id>/ui.mjs so the UI can `await import()` it at
+     * runtime — no static UI-side `import '@sisylabs/plugin-x/ui'`
+     * needed in production.
+     *
+     * Default: "./dist/ui.mjs" when unset.
+     * Plugins without a UI surface (daemon-only) can omit by setting "".
+     */
+    uiEntry?: string;
+}
+export interface SisyphusPlugin {
+    manifest: PluginManifest;
+    onActivate?: (ctx: PluginContext) => void | Promise<void>;
+    onDeactivate?: (ctx: PluginContext) => void | Promise<void>;
+    /** AgentImpls declared by this plugin. Daemon registers each on activation. */
+    agents?: AgentImpl[];
+    /** Keyed by skill id (must match a SkillDescriptor in the manifest). */
+    skillHandlers?: Record<string, SkillHandler>;
+}
+export interface PluginContext {
+    registry: RegistryAPI;
+    storage: PluginStorage;
+    log: (level: 'debug' | 'info' | 'warn' | 'error', msg: string, meta?: unknown) => void;
+}
+/**
+ * Per-plugin persistent key-value storage. Daemon provides a sandboxed
+ * instance to each plugin (keyed by manifest id) so plugin state survives
+ * restarts. Values must be JSON-serializable.
+ *
+ * Concurrency model: writes are debounced and best-effort durable; callers
+ * needn't await `set`/`delete` for correctness during the run, but the
+ * daemon flushes pending writes on shutdown.
+ */
+export interface PluginStorage {
+    get<T = unknown>(key: string): Promise<T | undefined>;
+    set(key: string, value: unknown): Promise<void>;
+    delete(key: string): Promise<void>;
+    clear(): Promise<void>;
+    keys(): Promise<string[]>;
+}
+export interface ChatMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    cards?: CardInstance[];
+}
+export interface RegistryAPI {
+    registerView(view: ViewDescriptor): Disposable;
+    registerCard(card: CardDescriptor): Disposable;
+    registerSkill(skill: SkillDescriptor, handler: SkillHandler): Disposable;
+    registerAgent(agent: AgentImpl): Disposable;
+    queryViews(filter?: {
+        region?: Region;
+    }): ViewDescriptor[];
+    queryCards(): CardDescriptor[];
+    querySkills(): SkillDescriptor[];
+    queryAgents(): AgentDescriptor[];
+}
+export interface Disposable {
+    dispose(): void;
+}
+export interface IPCRequest<T = unknown> {
+    type: 'request';
+    id: string;
+    method: string;
+    params?: T;
+}
+export interface IPCResponse<T = unknown> {
+    type: 'response';
+    id: string;
+    result?: T;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    };
+}
+export interface IPCEvent<T = unknown> {
+    type: 'event';
+    event: string;
+    data: T;
+}
+export type IPCMessage = IPCRequest | IPCResponse | IPCEvent;
+export declare const KernelEvents: {
+    readonly PlatformReady: "platform.ready";
+    readonly RegistrySnapshot: "registry.snapshot";
+    readonly RegistryViewAdded: "registry.view.added";
+    readonly RegistryViewRemoved: "registry.view.removed";
+    readonly RegistryCardAdded: "registry.card.added";
+    readonly RegistryCardRemoved: "registry.card.removed";
+    readonly RegistrySkillAdded: "registry.skill.added";
+    readonly RegistrySkillRemoved: "registry.skill.removed";
+    readonly RegistryAgentAdded: "registry.agent.added";
+    readonly RegistryAgentRemoved: "registry.agent.removed";
+    /**
+     * Dev-mode only: emitted by the daemon when a plugin's UI bundle file
+     * (dist/ui.mjs) changes on disk. UI hot-reloads the plugin in response.
+     * Payload: { pluginId: string, version: number } — version is a
+     * monotonic counter so the UI cache-busts dynamic imports cleanly.
+     */
+    readonly PluginUiBundleChanged: "plugin.ui.bundle.changed";
+};
+export type KernelEventName = (typeof KernelEvents)[keyof typeof KernelEvents];
+export interface RegistrySnapshot {
+    views: ViewDescriptor[];
+    cards: CardDescriptor[];
+    skills: SkillDescriptor[];
+    agents: AgentDescriptor[];
+}
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +1,34 @@
+/**
+ * @sisylabs/kernel — shared plugin contracts.
+ *
+ * Single source of truth for daemon ↔ UI ↔ plugin types.
+ *
+ * M2 architecture: multi-agent. The kernel hosts a Router that picks among
+ * agents contributed by plugins. Each agent runs its own LLM call and streams
+ * events directly to the UI (transparent pass-through through the daemon).
+ * Plugins describe when their agent should be spawned via `spawnHint`.
+ *
+ * See wiki: concepts/sisyphus-plugin-architecture.md
+ */
+// Well-known kernel event names. Plugins must use their own namespace-prefixed
+// event names (e.g. "plugin-base.chat.token") to avoid collisions.
+export const KernelEvents = {
+    PlatformReady: 'platform.ready',
+    RegistrySnapshot: 'registry.snapshot',
+    RegistryViewAdded: 'registry.view.added',
+    RegistryViewRemoved: 'registry.view.removed',
+    RegistryCardAdded: 'registry.card.added',
+    RegistryCardRemoved: 'registry.card.removed',
+    RegistrySkillAdded: 'registry.skill.added',
+    RegistrySkillRemoved: 'registry.skill.removed',
+    RegistryAgentAdded: 'registry.agent.added',
+    RegistryAgentRemoved: 'registry.agent.removed',
+    /**
+     * Dev-mode only: emitted by the daemon when a plugin's UI bundle file
+     * (dist/ui.mjs) changes on disk. UI hot-reloads the plugin in response.
+     * Payload: { pluginId: string, version: number } — version is a
+     * monotonic counter so the UI cache-busts dynamic imports cleanly.
+     */
+    PluginUiBundleChanged: 'plugin.ui.bundle.changed',
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAkUH,+EAA+E;AAC/E,mEAAmE;AACnE,MAAM,CAAC,MAAM,YAAY,GAAG;IAC1B,aAAa,EAAE,gBAAgB;IAC/B,gBAAgB,EAAE,mBAAmB;IACrC,iBAAiB,EAAE,qBAAqB;IACxC,mBAAmB,EAAE,uBAAuB;IAC5C,iBAAiB,EAAE,qBAAqB;IACxC,mBAAmB,EAAE,uBAAuB;IAC5C,kBAAkB,EAAE,sBAAsB;IAC1C,oBAAoB,EAAE,wBAAwB;IAC9C,kBAAkB,EAAE,sBAAsB;IAC1C,oBAAoB,EAAE,wBAAwB;IAC9C;;;;;OAKG;IACH,qBAAqB,EAAE,0BAA0B;CACzC,CAAC"}

package/dist/ui.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @sisylabs/kernel/ui — UI-side runtime registries.
+ *
+ * These maps live in browser-loaded code only. They're in the kernel package
+ * (not the ui package) so plugins can register renderers without depending on
+ * `@sisylabs/ui` — which would create a cycle, since the ui package depends
+ * on plugins for their UI bundles.
+ *
+ * React is `import type`-only — TypeScript strips it from emit, so the
+ * daemon's `@sisylabs/kernel` entry stays React-runtime-free.
+ */
+import type { ComponentType, ReactNode } from 'react';
+import type { Region, ViewDescriptor } from './index';
+export interface UIViewEntry {
+    descriptor: ViewDescriptor;
+    Component: ComponentType;
+}
+export declare function registerView(descriptor: ViewDescriptor, Component: ComponentType): () => void;
+export declare function getView(id: string): UIViewEntry | undefined;
+export declare function listViews(filter?: {
+    region?: Region;
+}): UIViewEntry[];
+export type CardRendererComponent = ComponentType<{
+    payload: unknown;
+}>;
+export declare function registerCardRenderer(type: string, Component: CardRendererComponent): () => void;
+export declare function getCardRenderer(type: string): CardRendererComponent | undefined;
+export type ProviderComponent = ComponentType<{
+    children: ReactNode;
+}>;
+export declare function registerProvider(Component: ProviderComponent): () => void;
+export declare function getProviders(): ProviderComponent[];
+//# sourceMappingURL=ui.d.ts.map

package/dist/ui.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.d.ts","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AACH,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AACtD,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAItD,MAAM,WAAW,WAAW;IAC1B,UAAU,EAAE,cAAc,CAAC;IAC3B,SAAS,EAAE,aAAa,CAAC;CAC1B;AAID,wBAAgB,YAAY,CAC1B,UAAU,EAAE,cAAc,EAC1B,SAAS,EAAE,aAAa,GACvB,MAAM,IAAI,CAQZ;AAED,wBAAgB,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS,CAE3D;AAED,wBAAgB,SAAS,CAAC,MAAM,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,WAAW,EAAE,CAKrE;AAID,MAAM,MAAM,qBAAqB,GAAG,aAAa,CAAC;IAAE,OAAO,EAAE,OAAO,CAAA;CAAE,CAAC,CAAC;AAIxE,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,qBAAqB,GAC/B,MAAM,IAAI,CAQZ;AAED,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,GACX,qBAAqB,GAAG,SAAS,CAEnC;AAQD,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC;IAAE,QAAQ,EAAE,SAAS,CAAA;CAAE,CAAC,CAAC;AAIvE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,iBAAiB,GAAG,MAAM,IAAI,CAMzE;AAED,wBAAgB,YAAY,IAAI,iBAAiB,EAAE,CAElD"}

package/dist/ui.js

@@ -0,0 +1,45 @@
+const views = new Map();
+export function registerView(descriptor, Component) {
+    if (views.has(descriptor.id)) {
+        throw new Error(`View id collision: ${descriptor.id}`);
+    }
+    views.set(descriptor.id, { descriptor, Component });
+    return () => {
+        views.delete(descriptor.id);
+    };
+}
+export function getView(id) {
+    return views.get(id);
+}
+export function listViews(filter) {
+    const all = Array.from(views.values());
+    return filter?.region
+        ? all.filter((e) => e.descriptor.region === filter.region)
+        : all;
+}
+const cardRenderers = new Map();
+export function registerCardRenderer(type, Component) {
+    if (cardRenderers.has(type)) {
+        throw new Error(`Card renderer collision: ${type}`);
+    }
+    cardRenderers.set(type, Component);
+    return () => {
+        cardRenderers.delete(type);
+    };
+}
+export function getCardRenderer(type) {
+    return cardRenderers.get(type);
+}
+const providers = [];
+export function registerProvider(Component) {
+    providers.push(Component);
+    return () => {
+        const idx = providers.indexOf(Component);
+        if (idx !== -1)
+            providers.splice(idx, 1);
+    };
+}
+export function getProviders() {
+    return [...providers];
+}
+//# sourceMappingURL=ui.js.map

package/dist/ui.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui.js","sourceRoot":"","sources":["../src/ui.ts"],"names":[],"mappings":"AAqBA,MAAM,KAAK,GAAG,IAAI,GAAG,EAAuB,CAAC;AAE7C,MAAM,UAAU,YAAY,CAC1B,UAA0B,EAC1B,SAAwB;IAExB,IAAI,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,CAAC,EAAE;QAC5B,MAAM,IAAI,KAAK,CAAC,sBAAsB,UAAU,CAAC,EAAE,EAAE,CAAC,CAAC;KACxD;IACD,KAAK,CAAC,GAAG,CAAC,UAAU,CAAC,EAAE,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;IACpD,OAAO,GAAG,EAAE;QACV,KAAK,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC,CAAC;IAC9B,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,OAAO,CAAC,EAAU;IAChC,OAAO,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AACvB,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,MAA4B;IACpD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACvC,OAAO,MAAM,EAAE,MAAM;QACnB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,UAAU,CAAC,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC;QAC1D,CAAC,CAAC,GAAG,CAAC;AACV,CAAC;AAMD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAiC,CAAC;AAE/D,MAAM,UAAU,oBAAoB,CAClC,IAAY,EACZ,SAAgC;IAEhC,IAAI,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,EAAE;QAC3B,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAC;KACrD;IACD,aAAa,CAAC,GAAG,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACnC,OAAO,GAAG,EAAE;QACV,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC7B,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,eAAe,CAC7B,IAAY;IAEZ,OAAO,aAAa,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;AACjC,CAAC;AAUD,MAAM,SAAS,GAAwB,EAAE,CAAC;AAE1C,MAAM,UAAU,gBAAgB,CAAC,SAA4B;IAC3D,SAAS,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;IAC1B,OAAO,GAAG,EAAE;QACV,MAAM,GAAG,GAAG,SAAS,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,GAAG,KAAK,CAAC,CAAC;YAAE,SAAS,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,YAAY;IAC1B,OAAO,CAAC,GAAG,SAAS,CAAC,CAAC;AACxB,CAAC"}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@sisylabs/kernel",
+  "version": "0.1.0",
+  "description": "Sisyphus kernel — shared plugin contracts (types) and UI runtime registries. The contract surface every Sisyphus plugin imports.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Devilsparta/Sisyphus.git",
+    "directory": "packages/kernel"
+  },
+  "homepage": "https://github.com/Devilsparta/Sisyphus#readme",
+  "keywords": [
+    "sisyphus",
+    "sisyphus-plugin-sdk",
+    "ai",
+    "plugin-system"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./ui": {
+      "types": "./dist/ui.d.ts",
+      "default": "./dist/ui.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "README.md"
+  ],
+  "peerDependencies": {
+    "react": "^18 || ^19"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/react": "^18.3.0",
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "rm -rf dist && tsc -p tsconfig.build.json"
+  }
+}

package/src/index.ts

@@ -0,0 +1,363 @@
+/**
+ * @sisylabs/kernel — shared plugin contracts.
+ *
+ * Single source of truth for daemon ↔ UI ↔ plugin types.
+ *
+ * M2 architecture: multi-agent. The kernel hosts a Router that picks among
+ * agents contributed by plugins. Each agent runs its own LLM call and streams
+ * events directly to the UI (transparent pass-through through the daemon).
+ * Plugins describe when their agent should be spawned via `spawnHint`.
+ *
+ * See wiki: concepts/sisyphus-plugin-architecture.md
+ */
+
+// ─── Panel Layout (VSCode-Lite, fixed four regions) ──────────────────────────
+
+export type Region = 'activity-bar' | 'side' | 'main' | 'bottom';
+
+/**
+ * A view is a unit rendered into a Panel Layout region.
+ * Metadata travels through the IPC; the renderer (React component / iframe /
+ * web component) lives on the UI side and is resolved by id.
+ */
+export interface ViewDescriptor {
+  /** Namespace-prefixed id, e.g. "plugin-base.view.canvas". */
+  id: string;
+  region: Region;
+  title: string;
+  /** Optional icon identifier (lucide name or URI). */
+  icon?: string;
+  defaultVisible?: boolean;
+}
+
+// ─── Chat cards ──────────────────────────────────────────────────────────────
+
+export interface CardDescriptor {
+  /** Namespace-prefixed type, e.g. "plugin-base.card.jsx". */
+  type: string;
+}
+
+export interface CardInstance {
+  type: string;
+  payload: unknown;
+  meta?: { id?: string; createdAt?: number };
+}
+
+// ─── Skills (OpenAI-tools-format capabilities) ───────────────────────────────
+
+export interface OpenAIToolSchema {
+  type: 'function';
+  function: {
+    name: string;
+    description?: string;
+    parameters?: Record<string, unknown>;
+  };
+}
+
+export interface SkillDescriptor {
+  /** Namespace-prefixed id, e.g. "plugin-base.skill.run-shell". */
+  id: string;
+  schema: OpenAIToolSchema;
+}
+
+export type SkillHandler = (
+  args: Record<string, unknown>,
+  ctx: SkillContext,
+) => Promise<unknown>;
+
+export interface SkillContext {
+  conversationId: string;
+}
+
+// ─── Agents (M2 multi-agent architecture) ────────────────────────────────────
+
+/**
+ * Metadata describing an agent. The router uses `spawnHint` (a short natural-
+ * language clause like "use when the user wants to build a React UI") to pick
+ * between agents when multiple are registered.
+ */
+export interface AgentDescriptor {
+  /** Namespace-prefixed id, e.g. "plugin-base.agent.react-designer". */
+  id: string;
+  displayName: string;
+  /** Short user-facing description shown in the UI. */
+  description: string;
+  /**
+   * Router hint: when should this agent be spawned? Read by the router (and
+   * eventually fed to an LLM router prompt in M4+) and by the UI to explain
+   * available capabilities.
+   */
+  spawnHint: string;
+  /**
+   * Optional explicit keywords the router uses for cheap deterministic
+   * matching (M3 strategy). Higher precision than parsing the prose
+   * spawnHint. M4+ will treat these as bias signals layered atop an LLM
+   * router.
+   */
+  triggerKeywords?: string[];
+  /**
+   * Tie-breaker / fan-out ordering signal (M14).
+   * Higher = preferred. When the router fan-outs across multiple agents
+   * (or chooses among tied candidates), it picks by descending priority.
+   * Default 0 when omitted.
+   */
+  priority?: number;
+}
+
+/**
+ * Streaming events an agent emits during a run. They pass-through the daemon
+ * to the UI without router interpretation; the router only observes `done`
+ * for completion / retry decisions.
+ *
+ * `source` is injected by the router at emit time (agents shouldn't set it
+ * themselves); it identifies which agent produced the event. Vital for
+ * fan-out / spawnAgent traces so the UI can route events to the right cell.
+ */
+interface EventBase {
+  source?: string;
+}
+export type AgentEvent =
+  | (EventBase & { type: 'token'; text: string })
+  | (EventBase & { type: 'reasoning'; text: string })
+  | (EventBase & { type: 'card'; card: CardInstance })
+  | (EventBase & {
+      type: 'tool_call';
+      id: string;
+      skill: string;
+      args: Record<string, unknown>;
+    })
+  | (EventBase & {
+      type: 'tool_result';
+      id: string;
+      result?: unknown;
+      error?: string;
+    })
+  | (EventBase & {
+      type: 'done';
+      reason: 'stop' | 'error' | 'cancelled';
+      error?: string;
+    });
+
+/**
+ * Context passed to an agent's `run`. The `emit` callback funnels events back
+ * through the daemon to the UI; `signal` is the abort signal the router (or
+ * the user) can fire to cancel a long-running agent.
+ */
+export interface AgentRunContext {
+  conversationId: string;
+  history: ChatMessage[];
+  emit: (event: AgentEvent) => void;
+  signal: AbortSignal;
+  /**
+   * Invoke a registered skill by id. The daemon dispatches to whichever
+   * plugin owns the skill handler. Agents should also `emit` matching
+   * `tool_call` / `tool_result` events so the UI can show the invocation
+   * trace; the platform does NOT emit those events automatically (the agent
+   * may choose to call a skill silently).
+   */
+  invokeSkill: (id: string, args: Record<string, unknown>) => Promise<unknown>;
+  /**
+   * Snapshot of every skill currently registered with the daemon. Agents
+   * use this to build the `tools` array for an LLM tool-calling call:
+   * each skill's `schema` is already OpenAI tools format.
+   *
+   * Note: OpenAI's function name pattern disallows '.', so skill.schema
+   * .function.name will not be the namespaced skill.id — the agent must
+   * keep its own name→id map when dispatching the LLM's tool_calls.
+   */
+  querySkills: () => SkillDescriptor[];
+  /**
+   * Spawn another agent as a sub-task (M14). The sub-agent's events stream
+   * through to the UI tagged with the sub-agent's id as `source`. Awaits
+   * the sub-agent to completion; its `done` is forwarded but does NOT end
+   * the parent's run — the parent must still emit its own `done`.
+   *
+   * The same skill-ACL applies to the sub-agent (it can only invoke its
+   * own plugin's skills + whatever its manifest declares).
+   */
+  spawnAgent: (agentId: string, userMessage: string) => Promise<void>;
+}
+
+/**
+ * A plugin-provided agent implementation. The daemon registers these and the
+ * router routes user messages to whichever one matches the situation.
+ *
+ * Contract: `run` MUST emit a final `{type:'done'}` event so the router knows
+ * the agent has completed (and can fire retries / handle timeouts). Failing
+ * to emit `done` leaves the conversation in an indeterminate state.
+ */
+export interface AgentImpl {
+  descriptor: AgentDescriptor;
+  run(userMessage: string, ctx: AgentRunContext): Promise<void>;
+}
+
+// ─── Plugin manifest (lives in package.json "sisyphus" field) ────────────────
+
+export interface PluginManifest {
+  /** Plugin id; used as namespace prefix for all contributed ids. */
+  id: string;
+  displayName?: string;
+  version: string;
+  /** Other plugin ids this one depends on. Daemon load order is topo-sorted. */
+  dependencies?: string[];
+  contributes?: {
+    views?: ViewDescriptor[];
+    cards?: CardDescriptor[];
+    skills?: SkillDescriptor[];
+    agents?: AgentDescriptor[];
+  };
+  /**
+   * Cross-plugin dependencies the daemon will gate at invocation time.
+   * By default a plugin's agents can only invoke skills under their own
+   * namespace; to call another plugin's skill the id must be listed here.
+   *
+   * Cross-plugin view/card use is mediated by registry queries (already
+   * shared) so doesn't need a declaration. Skills are different because
+   * they're invocable side-effects.
+   */
+  requires?: {
+    skills?: string[];
+  };
+  /**
+   * Path (relative to the plugin's package.json) of a browser-loadable
+   * ESM bundle exporting the plugin's UI surface (views, cardRenderers,
+   * providers). The daemon serves this file at
+   * GET /api/plugins/<id>/ui.mjs so the UI can `await import()` it at
+   * runtime — no static UI-side `import '@sisylabs/plugin-x/ui'`
+   * needed in production.
+   *
+   * Default: "./dist/ui.mjs" when unset.
+   * Plugins without a UI surface (daemon-only) can omit by setting "".
+   */
+  uiEntry?: string;
+}
+
+// ─── Plugin runtime entry (default export from plugin's main) ────────────────
+
+export interface SisyphusPlugin {
+  manifest: PluginManifest;
+
+  // Lifecycle
+  onActivate?: (ctx: PluginContext) => void | Promise<void>;
+  onDeactivate?: (ctx: PluginContext) => void | Promise<void>;
+
+  /** AgentImpls declared by this plugin. Daemon registers each on activation. */
+  agents?: AgentImpl[];
+
+  /** Keyed by skill id (must match a SkillDescriptor in the manifest). */
+  skillHandlers?: Record<string, SkillHandler>;
+}
+
+export interface PluginContext {
+  registry: RegistryAPI;
+  storage: PluginStorage;
+  log: (
+    level: 'debug' | 'info' | 'warn' | 'error',
+    msg: string,
+    meta?: unknown,
+  ) => void;
+}
+
+/**
+ * Per-plugin persistent key-value storage. Daemon provides a sandboxed
+ * instance to each plugin (keyed by manifest id) so plugin state survives
+ * restarts. Values must be JSON-serializable.
+ *
+ * Concurrency model: writes are debounced and best-effort durable; callers
+ * needn't await `set`/`delete` for correctness during the run, but the
+ * daemon flushes pending writes on shutdown.
+ */
+export interface PluginStorage {
+  get<T = unknown>(key: string): Promise<T | undefined>;
+  set(key: string, value: unknown): Promise<void>;
+  delete(key: string): Promise<void>;
+  clear(): Promise<void>;
+  keys(): Promise<string[]>;
+}
+
+export interface ChatMessage {
+  role: 'system' | 'user' | 'assistant' | 'tool';
+  content: string;
+  cards?: CardInstance[];
+}
+
+// ─── Registry API (central service-discovery contract) ───────────────────────
+//
+// All plugin contributions flow through this API. No implicit discovery, no
+// global pollution. Disposing a registration must fully revoke the capability
+// (UI removes view, agent service stops offering skill, etc).
+
+export interface RegistryAPI {
+  registerView(view: ViewDescriptor): Disposable;
+  registerCard(card: CardDescriptor): Disposable;
+  registerSkill(skill: SkillDescriptor, handler: SkillHandler): Disposable;
+  registerAgent(agent: AgentImpl): Disposable;
+
+  queryViews(filter?: { region?: Region }): ViewDescriptor[];
+  queryCards(): CardDescriptor[];
+  querySkills(): SkillDescriptor[];
+  queryAgents(): AgentDescriptor[];
+}
+
+export interface Disposable {
+  dispose(): void;
+}
+
+// ─── IPC envelopes (HTTP + WebSocket) ───────────────────────────────────────
+//
+// Wire format decision (2026-05-20): custom protocol with three frame kinds
+// distinguished by a `type` discriminator. See wiki — chosen over JSON-RPC 2.0
+// for clearer separation between request/response (RPC) and event (pubsub).
+
+export interface IPCRequest<T = unknown> {
+  type: 'request';
+  id: string;
+  method: string;
+  params?: T;
+}
+
+export interface IPCResponse<T = unknown> {
+  type: 'response';
+  id: string;
+  result?: T;
+  error?: { code: number; message: string; data?: unknown };
+}
+
+export interface IPCEvent<T = unknown> {
+  type: 'event';
+  event: string;
+  data: T;
+}
+
+export type IPCMessage = IPCRequest | IPCResponse | IPCEvent;
+
+// Well-known kernel event names. Plugins must use their own namespace-prefixed
+// event names (e.g. "plugin-base.chat.token") to avoid collisions.
+export const KernelEvents = {
+  PlatformReady: 'platform.ready',
+  RegistrySnapshot: 'registry.snapshot',
+  RegistryViewAdded: 'registry.view.added',
+  RegistryViewRemoved: 'registry.view.removed',
+  RegistryCardAdded: 'registry.card.added',
+  RegistryCardRemoved: 'registry.card.removed',
+  RegistrySkillAdded: 'registry.skill.added',
+  RegistrySkillRemoved: 'registry.skill.removed',
+  RegistryAgentAdded: 'registry.agent.added',
+  RegistryAgentRemoved: 'registry.agent.removed',
+  /**
+   * Dev-mode only: emitted by the daemon when a plugin's UI bundle file
+   * (dist/ui.mjs) changes on disk. UI hot-reloads the plugin in response.
+   * Payload: { pluginId: string, version: number } — version is a
+   * monotonic counter so the UI cache-busts dynamic imports cleanly.
+   */
+  PluginUiBundleChanged: 'plugin.ui.bundle.changed',
+} as const;
+
+export type KernelEventName = (typeof KernelEvents)[keyof typeof KernelEvents];
+
+export interface RegistrySnapshot {
+  views: ViewDescriptor[];
+  cards: CardDescriptor[];
+  skills: SkillDescriptor[];
+  agents: AgentDescriptor[];
+}

package/src/ui.ts

@@ -0,0 +1,93 @@
+/**
+ * @sisylabs/kernel/ui — UI-side runtime registries.
+ *
+ * These maps live in browser-loaded code only. They're in the kernel package
+ * (not the ui package) so plugins can register renderers without depending on
+ * `@sisylabs/ui` — which would create a cycle, since the ui package depends
+ * on plugins for their UI bundles.
+ *
+ * React is `import type`-only — TypeScript strips it from emit, so the
+ * daemon's `@sisylabs/kernel` entry stays React-runtime-free.
+ */
+import type { ComponentType, ReactNode } from 'react';
+import type { Region, ViewDescriptor } from './index';
+
+// ─── View registry ─────────────────────────────────────────────────────────
+
+export interface UIViewEntry {
+  descriptor: ViewDescriptor;
+  Component: ComponentType;
+}
+
+const views = new Map<string, UIViewEntry>();
+
+export function registerView(
+  descriptor: ViewDescriptor,
+  Component: ComponentType,
+): () => void {
+  if (views.has(descriptor.id)) {
+    throw new Error(`View id collision: ${descriptor.id}`);
+  }
+  views.set(descriptor.id, { descriptor, Component });
+  return () => {
+    views.delete(descriptor.id);
+  };
+}
+
+export function getView(id: string): UIViewEntry | undefined {
+  return views.get(id);
+}
+
+export function listViews(filter?: { region?: Region }): UIViewEntry[] {
+  const all = Array.from(views.values());
+  return filter?.region
+    ? all.filter((e) => e.descriptor.region === filter.region)
+    : all;
+}
+
+// ─── Card renderer registry ────────────────────────────────────────────────
+
+export type CardRendererComponent = ComponentType<{ payload: unknown }>;
+
+const cardRenderers = new Map<string, CardRendererComponent>();
+
+export function registerCardRenderer(
+  type: string,
+  Component: CardRendererComponent,
+): () => void {
+  if (cardRenderers.has(type)) {
+    throw new Error(`Card renderer collision: ${type}`);
+  }
+  cardRenderers.set(type, Component);
+  return () => {
+    cardRenderers.delete(type);
+  };
+}
+
+export function getCardRenderer(
+  type: string,
+): CardRendererComponent | undefined {
+  return cardRenderers.get(type);
+}
+
+// ─── Provider registry ─────────────────────────────────────────────────────
+//
+// Plugins that need to wrap the host with a React context provider register
+// it here. The host renders a <ProviderStack> that nests them around the
+// layout shell. Order: registration order, outermost first.
+
+export type ProviderComponent = ComponentType<{ children: ReactNode }>;
+
+const providers: ProviderComponent[] = [];
+
+export function registerProvider(Component: ProviderComponent): () => void {
+  providers.push(Component);
+  return () => {
+    const idx = providers.indexOf(Component);
+    if (idx !== -1) providers.splice(idx, 1);
+  };
+}
+
+export function getProviders(): ProviderComponent[] {
+  return [...providers];
+}