@wujie-shell/sdk

@wujie-shell/sdk contains the renderer-facing TypeScript types and small helpers for product UI projects that consume wujie-shell.

The runtime object is injected as window.wujieShell: Electron uses preload and the local Web Host uses a page bootstrap. UI code imports the same public entry and Hooks in both environments.

Responsibility

• Define the public renderer API shape.
• Define common event/status types.
• Provide helpers for shell payloads.
• Keep UI code independent from Electron internals.
• Keep Electron and Web implementations in separate source directories while exposing one host-neutral Hook surface.

This package must stay product-agnostic. Product-specific Agent, Skill, Plugin, and Workflow behavior belongs in apps/<product>.

Exported Types

import type {
  ChatStreamEvent,
  GatewayStatus,
  ShellMediaItem,
  ShellResult,
  Unsubscribe,
  WindowWujieShell,
} from '@wujie-shell/sdk'

Exported Helpers

import { extractShellMedia } from '@wujie-shell/sdk'

extractShellMedia(payload) reads OpenClaw payloads shaped like:

{
  showInUI: true,
  paths: Array<{
    uri: string
    mimeType: string
    id?: string
    name?: string
    size?: number
    fileKind?: string
    metadata?: Record<string, unknown>
    persistToGeneratedFiles?: boolean
  }>
}

and returns a normalized ShellMediaItem[]. Shell Core also uses these generic descriptors when projecting newly indexed session artifacts into generated-files; producer metadata remains opaque.

Runtime Access

Use the global injected object:

const shell = window.wujieShell
const status = await shell.openclaw.gatewayStatus()

Renderer code should not import ipcRenderer or use Electron APIs directly.

Desktop shell abilities are also consumed through the same global object:

await shell.window.openDevTools()

const off = shell.window.onDevToolsShortcut(event => {
  console.log(event.accelerator)
})

Model provider settings can be read and written through the injected shell API:

await shell.models.setSettings({
  provider: 'wujieai',
  apiKey: '...',
  modelName: 'auto',
  modelBaseUrl: 'https://model.example.com',
})

UI Framework Boundary

@wujie-shell/sdk keeps the base entry framework-agnostic. React products can import the optional subpath @wujie-shell/sdk/react, which wraps the injected window.wujieShell object for gateway status, sessions, chat history, chat streaming, and ask-user-question events.

import { useGatewayStatus, useSessions } from '@wujie-shell/sdk/react'

Use useWujieShell() when direct access is needed. It works in Electron and Web because the active host installs the same facade contract before renderer code runs. Product UI must not select @wujie-shell/sdk/electron or @wujie-shell/sdk/web itself.

Product-specific UI, routing, assets, Agent/Skill/Plugin behavior, and message rendering still belong in product workspaces such as apps/desktop-cn/src. SDK hooks must stay product-agnostic and must not import product components.

API Groups

• window.wujieShell.app
• window.wujieShell.window
• window.wujieShell.openclaw
• window.wujieShell.terminal
• window.wujieShell.agents
• window.wujieShell.files
• window.wujieShell.workspace
• window.wujieShell.skills
• window.wujieShell.sessions
• window.wujieShell.cron
• window.wujieShell.models
• window.wujieShell.config
• window.wujieShell.chat

See ../../docs/wujie-shell-sdk-api.md for the detailed API manual.