DEVELOPER DOCUMENTATION

SpaceSDK Windows integration guide

Baseline: SpaceSDK 0.1.0-preview.1, September 6, 2026, Developer API 1. The independent package is built from the current source and includes handlers plus optional knowledge. The examples below explain integration; they are not proof of a signed application installation.

1. Supported application shapes

The current concrete integration target is a Windows sandboxed-window inside a signed Application package, registered and opened by the Host. Business handlers use Plugin dependencies declared and linked by the application; the application owns its business data.

“No LUMII source changes” does not mean “no third-party development.” You still build the workspace, manifest, handlers, business authorization, and trusted Plugin dependencies. Do not bypass a missing capability with self-asserted account data, raw Native commands, or Gateway credentials.

2. Runtime requirements

1. The user is in a LUMII Windows Host session that can admit business applications; Host/Core, the adapter database, and required dependencies are ready.
2. The Application was registered through the trusted DStore installation flow and opened by the Host. Double-clicking HTML, serving a local page, or copying files into an install directory does not establish identity.
3. lumii.app.json declares Windows, developerApi: 1, and the technical capabilities actually approved.
4. The user binds required Agent or Team employments in trusted DStore configuration. The application does not select the global account directory or create Agents.
5. Browser JS, type declarations, Host/Core, and each Plugin's exact published releaseId belong to one verified combination.

Do not read Host database connections, path registries, or Gateway credentials. createNativeApplicationRuntimeContext() returns Host-established application identity.

3. Install and import

Download lumii-spacesdk-0.1.0-preview.1.tgz, verify it against SHA256SUMS.txt, place it in your project, and install the exact file:

npm init -y
npm install --save-exact ./lumii-spacesdk-0.1.0-preview.1.tgz

import {
  createNativeApplicationRuntimeContext,
  mountApplicationChat,
} from "@lumii/spacesdk/chat";

The preview is not on the public npm Registry and has no runtime dependencies. Your project supplies TypeScript and the browser bundler. Do not use the default @lumii/sdk entry or old dist/developer.mjs. Bundle the installed SpaceSDK or ship every required ESM chunk in the signed file index; do not replace it at runtime from an arbitrary CDN or mix old JS with new declarations.

4. Application package declarations

Full chat usually needs employment.read, session.read, session.manage, session.send, session.history, and session.cancel. Handler calls need business.invoke. KBrain, global model management, and task execution are not implicit baseline requirements.

5. Initialization and explicit employment selection

const context = await createNativeApplicationRuntimeContext();
const descriptor = await context.platform.describe();
if (descriptor.apiVersion !== 1) throw new Error("Incompatible Host API version.");

const grants = new Set(context.application.grantedTechnicalCapabilities);
for (const capability of ["employment.read", "session.read", "session.manage",
  "session.send", "session.history", "session.cancel"]) {
  if (!grants.has(capability)) throw new Error(`Missing capability: ${capability}`);
}

const page = await context.platform.employments.listOwnBindings({ limit: 100 });
// Present bindingId/displayName/kind/state and continue through nextCursor.
// Do not select items[0] or infer a binding by name.

descriptor.unsupportedOperations is a list of explicitly rejected methods, not a guarantee for every method not listed. It currently names schedule.runNow; that does not make active scheduling or resume executable.

6. Embedded chat

async function openSelectedChat(container, selectedBindingId) {
  const binding = await context.platform.employments.getOwnBinding(selectedBindingId);
  if (binding.state !== "active") throw new Error("The selected employment is inactive.");
  return mountApplicationChat(container, {
    sessions: context.platform.sessions,
    bindingId: binding.bindingId,
    kind: binding.kind,
    title: binding.displayName,
    label: "Business discussion",
    onError: (message) => console.error(message),
  });
}

Dispose the old view before switching and dispose on route exit. Disposal does not delete the foundation session. This is an independent Shadow DOM chat view, not a pixel-identical reuse of LUMII's main chat. Build your own localized UI with ApplicationChatController or platform.sessions when needed.

Team execution requires explicit member selection and targets. It does not guess a leader or downgrade to a normal Agent send. Partial success may already have changed business data even when the overall request fails, so read back authoritative business state.

7. Shared business handlers

if (!context.platform.handlers?.invoke) throw new Error("This SDK build lacks handlers.");
if (!grants.has("business.invoke")) throw new Error("business.invoke is not granted.");

const result = await context.platform.handlers.invoke({
  dependencyId: "inventory-tools",
  operation: "inventory_application",
  input: { operation: "products.list", input: {} },
});

The path is business page → SpaceSDK → Host admission and dependency validation → linked Plugin → application-owned logic and storage. Agents reach the same handler through existing tool mechanisms. Handlers must not trust an accountId, installation path, or foundation session key supplied by a page or model. The application owns business authorization, input validation, concurrency checks, transactions, and business idempotency; an SDK requestId is only correlation.

8. Signing, installation, and acceptance

Use the existing DStore flow: prepare Application and Plugin → sign with the real user identity → submit an exact version → platform review → publisher explicitly publishes the approved version → read back the release → trusted Host installation → configure employments → open from the Host.

Plugin and Application are different package kinds. Publish the Plugin first and place its exact release ID in the Application build input. An unsigned example receipt is not trusted installation authority. Account signing, platform release signing, and Host trust roots have separate responsibilities.

At minimum, test real account admission, employment selection, session creation, a real message and tool execution, shared page/Agent business state, request recovery, Team partial success, loss of authority after account switch, data preservation on update, and the user's retain/delete choice on uninstall. Preserve exact versions and receipts; type checks, a page that opens, or mocks do not replace acceptance.

9. Troubleshooting

See the API reference for error codes, recovery, subscription acknowledgement, and cancellation.