DEVELOPER DOCUMENTATION

SpaceSDK Windows API, permissions, and recovery

Baseline: SpaceSDK 0.1.0-preview.1, September 6, 2026, Developer API 1. This page documents the public ports and call semantics. Complete fields ship in dist/*.d.ts. An SDK port does not by itself prove real Host acceptance; see release and support scope.

1. Entry points and common parameters

@lumii/spacesdk/chat exports createNativeApplicationRuntimeContext, createNativeApplicationRuntimePlatform, NativeDeveloperBridgeCallError, mountApplicationChat, and ApplicationChatController. Complete contracts and other types are in @lumii/spacesdk. Both are browser-bundleable ESM and do not include a Gateway client. SPACESDK_API_VERSION is the unified protocol constant; LUMII_DEVELOPER_API_VERSION remains for compatibility.

• createNativeApplicationRuntimeContext() returns { application, platform } with Host-established application identity and bound ports.
• platform.describe() reports the Developer API version, Host version, granted capabilities, limits, and explicitly unsupported operations.
• Collection methods use cursor pagination. Continue with nextCursor until it is absent.
• Caller-supplied account IDs, installation paths, raw session keys, or global Agent IDs are not authority.

2. Agent and Team employments

platform.employments is limited to bindings owned by the current application and account.

A binding contains an opaque bindingId, application employment ID, display name, agent or team kind, state, and revision. Show the list and require explicit user selection. Do not choose the first item, infer by display name, or persist a foundation identity as a replacement for the binding.

3. Sessions, messages, and Teams

platform.sessions provides application-scoped session operations. Creating and sending require session.manage or session.send; reading and history require the corresponding read grants.

Use sessionRef, requestRef, and member result references as opaque values. The SDK has no public attach(sessionKey) escape hatch.

4. Acceptance, recovery, and events

A returned acceptance receipt means the Host admitted the request, not that model or tool work succeeded. Persist the receipt before displaying durable progress. After a disconnect, recover with the same requestRef; do not create a duplicate request simply because the response was lost.

• Subscribe to the application-scoped event stream and acknowledge events according to the delivered cursor contract.
• Handle reconnects, duplicate delivery, and terminal-state readback. Event delivery is a projection; query current state when correctness matters.
• Team requests can have partial member success. Read every member result and then reload authoritative business data.
• Dispose subscriptions and chat controllers on route exit. Account logout, application disable, update, or uninstall can revoke the caller generation.

5. Business handlers

platform.handlers.invoke requires business.invoke and calls only a Plugin dependency declared and linked by this application.

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

The Host verifies application identity, grants, dependency linkage, and runtime scope. The Plugin owns the actual operation contract. Validate isError and the Plugin-specific result shape. Generic TypeScript parameters do not validate runtime data. The application remains responsible for business authorization, input validation, concurrency control, transactions, and business idempotency.

6. Dock

platform.dock requires dock.manage. An application can register, update, or remove only its own declared Dock entry. The Host owns final placement and lifecycle state. A successful SDK call does not authorize another application's route or icon.

7. Scheduling limitations

platform.schedules requires schedule.manage. The current SDK can describe limited schedule records, but the Host has no generic sandbox task executor for application work. schedule.runNow is explicitly unsupported, and active creation or resume must not be presented as executable merely because their types exist. Surface the concrete Host error instead of substituting another execution path.

8. Optional KBrain extension

platform.knowledge is optional and must be capability-checked. It is not a business database API and does not expose raw Memory, Wiki, or Dreaming administration. A declared port does not prove that the required Native/Core extension version and authorization are available on a target Host.

9. Error handling

Native calls reject with NativeDeveloperBridgeCallError. Preserve and display the concrete code, message, retryability, and request reference where provided.

Do not turn failures into false success. Log enough correlation data to diagnose the exact SDK, Host, application, Plugin release, and request without exposing credentials or cross-application identities.