Introduction

@cutos/core is the TypeScript-friendly Core SDK for CUTOS 4.0. It provides the system-call API used by LWA applications, Node Providers, tools, and services running in the CUTOS ecosystem.

CUTOS 4.0 uses a Capability/Provider model:

• Capability: a named CUTOS system ability consumed by an LWA, service, or AI agent.
• Provider: a Node.js module or process that implements a Capability.
• Contract: a capability.contract.json file that describes methods, events, errors, and permissions.

Hardware Device/Driver APIs remain available as the compatibility layer, but new CUTOS 4.0 applications should use Capability/Provider and Promise-first APIs.

Core API Module Components

Platform

• CoreAPI is the main entry point for connecting to CUTOS runtime.
• It provides Promise-first methods for reading platform, configuration, box, device, volume, proxy, and shell information.

Capability And Provider

• cutos.capability(name) creates a client for calling a CUTOS capability.
• cutos.provider(name) creates a Node-side provider implementation.
• Capability.call() maps to request-response IPC.
• Provider.method() registers a method handler.
• Provider.emit() publishes events to consumers.

IPC

• IPC is a lower-level channel API for local and cross-device communication.
• Prefer Capability/Provider for product APIs; use IPC for diagnostics, tools, and experimental services.

Database

• CoreClass.Database provides Promise-first access to the CUTOS local database.
• Database.Table supports table creation, insert, update, delete, query, sync, and mirror-oriented operations.

Notification

• Notification supports registering, unregistering, and emitting system/application notifications.

Logging

• Logger supports info, warning, error, and debug logs.

Error Model

• CUTOS 4.0 normalizes errors to CutosError.
• CutosError includes code, message, and optional detail.

Table Of Contents

1. Quick Start
2. Platform API
3. Capability API
4. Provider API
5. IPC API
6. Database API
7. Notification API
8. Logger API
9. Error Model
10. Capability Contract
11. Mock Dev
12. Documentation

Quick Start

Install

npm install @cutos/core

Import

import {
  CoreAPI,
  CoreClass,
  CoreSimulator,
  CutosError,
  cutos
} from "@cutos/core"

Initialize

await CoreAPI.init("localhost")

During development, connect to a target CUTOS device:

await CoreAPI.init("192.168.1.100")

LWA: Consume A Capability

await CoreAPI.init("localhost")

const hello = cutos.capability("hello-device")

const result = await hello.call<
  { message: string },
  { message: string }
>("echo", { message: "hello" })

console.log(result.message)

Node: Implement A Provider

await CoreAPI.init("localhost")

const provider = cutos.provider("hello-device")

provider.method<
  { message: string },
  { message: string }
>("echo", async params => {
  return { message: params.message }
})

provider.emit("statusChanged", {
  status: "connected",
  message: "hello-device ready"
})

Mock Dev

Use Mock Dev when developing an LWA without a local CUTOS Node.

import { CoreAPI, cutos, CutosMock } from "@cutos/core"

CutosMock.install({
  capabilities: {
    "hello-device": {
      methods: {
        echo: params => params
      }
    }
  }
})

await CoreAPI.init("mock")

const hello = cutos.capability("hello-device")
const result = await hello.call("echo", { message: "hello" })

For simple UI development, set the CUTOS host to mock and keep application code unchanged:

VITE_CUTOS_BROKER_URL=mock

Mock Dev is intended for UI and SDK integration development. Real IPC, WebView host behavior, and Node Provider behavior should still be verified with a CUTOS Node before release.

Platform API

CoreAPI.init

Connect to CUTOS runtime.

await CoreAPI.init(host?: string | null)

• host: CUTOS host address. Defaults to localhost.
• Returns: Promise<string>.

Example:

await CoreAPI.init("localhost")

CoreAPI.connected

Check whether the SDK is connected.

const connected = CoreAPI.connected()

CoreAPI.getVersion

Get SDK version.

const version = CoreAPI.getVersion()

CoreAPI.getPlatform

Get platform information.

type PlatformInfo = {
  arch: string
  platform: string
  type: string
  release: string
}

const platform = await CoreAPI.getPlatform<PlatformInfo>()

CoreAPI.getConfig

Get CUTOS runtime configuration.

const config = await CoreAPI.getConfig<Record<string, unknown>>()

CoreAPI.getBoxInfo

Get host box information.

const box = await CoreAPI.getBoxInfo<Record<string, unknown>>()

CoreAPI.getDeviceInfo

Get registered CUTOS device identity information.

const deviceInfo = await CoreAPI.getDeviceInfo<Record<string, unknown>>()

CoreAPI.getSignInfo / CoreAPI.getSignGroupInfo

Get sign and sign group metadata.

const signInfo = await CoreAPI.getSignInfo<Record<string, unknown>>()
const groupInfo = await CoreAPI.getSignGroupInfo<Record<string, unknown>>()

CoreAPI.getVolume / CoreAPI.setVolume

const volume = await CoreAPI.getVolume<number>()
await CoreAPI.setVolume(70)

CoreAPI.setHttpProxy

Set a runtime HTTP proxy to avoid LWA cross-origin issues during development.

type ProxyResult = {
  path: string
  target: string
}

const proxy = await CoreAPI.setHttpProxy<ProxyResult>(
  "api",
  "https://www.cut-os.com"
)

CoreAPI.shell

Execute a shell command through CUTOS runtime.

const pwd = await CoreAPI.shell<string>("pwd")

Use this API carefully. It should not be exposed to untrusted LWA code without permissions.

Capability API

cutos.capability

Create a capability client.

const capability = cutos.capability("hello-device")

CoreAPI.capability() is equivalent.

const capability = CoreAPI.capability("hello-device")

capability.call

Call a Provider method.

const result = await capability.call<
  { message: string },
  { message: string }
>("echo", { message: "hello" })

Set a per-call timeout:

await capability.call(
  "connect",
  { name: "demo" },
  { timeout: 3000 }
)

capability.on

Subscribe to Provider events.

const unsubscribe = capability.on<{
  status: "idle" | "connected" | "error"
  message?: string
}>("statusChanged", data => {
  console.log(data.status)
})

capability.off

Remove one listener or all listeners for an event.

capability.off("statusChanged")

capability.dispose

Clear listeners and release the underlying subscription.

capability.dispose()

Provider API

cutos.provider

Create a Provider.

const provider = cutos.provider("hello-device")

CoreAPI.provider() is equivalent.

const provider = CoreAPI.provider("hello-device")

provider.method

Register a method handler.

provider.method<
  { message: string },
  { message: string }
>("echo", async params => {
  return { message: params.message }
})

Use context when raw command information is needed.

provider.method<{ name: string }, { connected: boolean }>(
  "connect",
  async (params, context) => {
    console.log(context.command.cmd)
    return { connected: true }
  }
)

Throw CutosError for expected business errors.

throw new CutosError("HELLO_DEVICE_UNAVAILABLE", "The hello device is unavailable.")

provider.emit

Emit an event.

provider.emit("statusChanged", {
  status: "connected",
  message: "hello-device ready"
})

provider.dispose

Clear methods and release the underlying command listener.

provider.dispose()

IPC API

IPC is a lower-level channel API. Prefer Capability/Provider for product APIs.

CoreAPI.getIPC

const ipc = CoreAPI.getIPC()
const remote = CoreAPI.getIPC("192.168.1.149")

ipc.call

const result = await ipc.call<
  { left: number; right: number },
  { sum: number }
>("math.add", { left: 2, right: 2 })

ipc.callWithOptions

await ipc.callWithOptions(
  "math.add",
  { left: 2, right: 2 },
  { timeout: 3000 }
)

ipc.on

const off = ipc.on<{ left: number; right: number }, { sum: number }>(
  "math.add",
  (args, respond) => {
    respond({ sum: args.left + args.right })
  }
)

off?.()

ipc.sendTo

Fire-and-forget message.

ipc.sendTo("diagnostic.event", { time: Date.now() })

Database API

CUTOS database uses a key-value table model. Values can be arbitrary JSON objects.

Database

const database = new CoreClass.Database()
await database.connect()

database.run

const rows = await database.run<Array<Record<string, unknown>>>(
  "select * from device"
)

Database.Table

const table = new CoreClass.Database.Table("device", database)

table.create

await table.create({
  keyName: "id",
  keyType: "INTEGER"
})

table.insert

await table.insert(
  { type: "printer", name: "HP-1" },
  { tid: "tra-001" }
)

table.insertById / table.insertByKey

await table.insertById(1, { type: "printer", name: "HP-1" })
await table.insertByKey("printer-1", { type: "printer", name: "HP-1" })

table.update / table.updateByKey

await table.update(1, { type: "printer", name: "HP-2" })
await table.updateByKey("printer-1", { type: "printer", name: "HP-2" })

table.delete

await table.delete(1)

table.query APIs

const byId = await table.query<Array<Record<string, unknown>>>(1)
const byKey = await table.queryByKey<Array<Record<string, unknown>>>("printer-1")
const byTid = await table.queryByTid<Array<Record<string, unknown>>>("tra-001")
const all = await table.queryAll<Array<Record<string, unknown>>>()

table.queryUnsynced

const rows = await table.queryUnsynced<Array<Record<string, unknown>>>({ limit: 100 })

table.sync

await table.sync(1)

Notification API

CoreAPI.getNotification

const notification = CoreAPI.getNotification()

notification.register

notification.register(data => {
  console.log(data)
})

notification.unregister

notification.unregister()

notification.emit

notification.emit("notification-1", "msg-1")

System notification example:

type NetworkNotification = {
  event: "networkConnection"
  msg: boolean
}

Logger API

CoreAPI.getLogger

const logger = CoreAPI.getLogger()

logger.info / warning / error / debug

logger.info("hello-device", "provider started")
logger.warning("hello-device", "slow response")
logger.error("hello-device", "provider failed")
logger.debug("hello-device", "debug detail")

The third argument is optional and defaults to LWA.

logger.info("hello-provider", "started", "Provider")

Error Model

CUTOS 4.0 normalizes SDK errors to CutosError.

try {
  await cutos.capability("hello-device").call("connect", { name: "demo" })
} catch (error) {
  if (error instanceof CutosError) {
    console.log(error.code)
    console.log(error.message)
    console.log(error.detail)
  }
}

Common error codes include:

CUTOS_TIMEOUT
CUTOS_CORE_ERROR
DRIVER_INIT_TIMEOUT
DRIVER_INIT_ERROR
METHOD_NOT_FOUND
PROVIDER_ERROR

Capability Contract

Capabilities should be described by capability.contract.json.

{
  "schemaVersion": "0.1",
  "name": "hello-device",
  "version": "1.0.0",
  "type": "device",
  "methods": {},
  "events": {},
  "errors": {},
  "permissions": []
}

Contracts are the source of truth for future SDK generation, Provider stubs, documentation, tests, permissions, and AI tool schemas.

Documentation

Full CUTOS 4.0 SDK API guide:

docs/CUTOS-4.0-SDK-API.md

Capability contract spec:

docs/CUTOS-Capability-Contract-v0.md