@zephyrcloudio/harness-sdk

The embedded Node.js composition for Ze Harness.

createEmbeddedHarness opens SQLite, uses the Node Server host to create the real Fetch handler, and returns a typed Client using injected Fetch. listenEmbeddedHarness can add a loopback listener to the same instance.

import { createEmbeddedHarness, listenEmbeddedHarness } from '@zephyrcloudio/harness-sdk';

Creation is scoped and requires cwd plus an explicit databaseFilename. Several processes may open the same database file; readers run concurrently and writers serialize. Provider keys live in the global auth.json (override with authFilePath), shared by every database. Plugins supplied by config or inlinePlugins are trusted and unsandboxed.

The SDK re-exports authFileDataRoot() and defaultAuthFilePath() from Server Node. The shared state directory is $XDG_DATA_HOME/ze-harness when XDG_DATA_HOME is absolute; otherwise it is ~/.local/share/ze-harness on Unix and %LOCALAPPDATA%\ze-harness on Windows (home AppData\Local fallback). Existing Windows legacy state is retained while its daemon is live, then migrated on a subsequent invocation with a compatibility junction. Conflicting roots are reported explicitly. See Server Node's state-path guidance for migration and locked-directory handling. databaseFilename remains caller-supplied.

Use sessionPluginArtifacts to configure trusted Session package resolution:

createEmbeddedHarness({
  cwd: process.cwd(),
  databaseFilename: './harness.sqlite',
  config: {
    permissions: [{ action: '*', resource: '*', effect: 'ask' }],
    permissionMatching: { caseSensitive: true },
  },
  sessionPluginArtifacts: {
    cacheDirectory: '/path/to/cache',
    packageManager: { command: 'npm', registry: 'https://registry.npmjs.org' },
    resolveTimeoutMs: 60_000,
    installTimeoutMs: 120_000,
  },
});

The limits are optional and default to unlimited. See the Server Node README for source identity and trust details.

The embedded SDK uses the same Node Server configuration path as serve, including ordered permissions, permissionMatching, and approval.timeoutMs. Native providers (OpenAI, OpenRouter) and the file-backed Provider Authority are composed automatically on the embedded instance. Session configuration and durable saved permissions are available through the returned Client. Pass credentialMode: 'injected-only' with providerCredentials, mcpCredentialResolver, mcpOAuthTokenResolver, contentResolver, toolDispatch, and providerDefinitions to run as an injected-port host with no ambient credential discovery.

See the embedded quickstart.

Public TypeScript exports

  • authFileDataRoot
  • ClientConnection
  • ClientDisconnection
  • createEmbeddedHarness
  • CreateEmbeddedHarnessOptions
  • Daemon
  • DAEMON_BASE_PORT
  • DAEMON_FILE_NAME
  • DAEMON_LOG_FILE_NAME
  • DAEMON_MAX_PORT
  • DAEMON_STARTUP_FILE_NAME
  • daemonDirectory
  • DaemonError
  • DaemonOptionsMismatch
  • DaemonStartObserver
  • DaemonStartupProgress
  • DaemonStartupReporter
  • DaemonStartupStep
  • DaemonStatusValue
  • DaemonTransportOptions
  • DaemonVersionMismatch
  • DECLARATIVE_SESSION_PLUGIN
  • defaultAuthFilePath
  • EmbeddedHarness
  • EmbeddedHarnessError
  • listenEmbeddedHarness
  • ListenOptions
  • makeDaemonLog
  • makeDaemonStartupReporter
  • makeMcpSecretCredentialResolver
  • NodeListener
  • resolveProjectIdentity
  • ServerListenError
  • startDaemonLogTrim
  • StorageMigrationProgress