# `@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.

```ts
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](/docs/server-node.md) for
migration and locked-directory handling. `databaseFilename` remains caller-supplied.

Use `sessionPluginArtifacts` to configure trusted Session package resolution:

```ts
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](https://github.com/ZephyrCloudIO/ze-harness/blob/main/README.md#embedded-sdk).


## 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`

---

Generated from [`packages/sdk/README.md`](https://github.com/ZephyrCloudIO/ze-harness/blob/main/packages/sdk/README.md).