@stateforge-labs/herdr-sdk 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,18 @@
+MIT License
+
+Copyright (c) 2026 the @stateforge-labs/herdr-sdk authors (including its intermediate port) and brooswit (jsHerdrSDK)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software
+and associated documentation files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or
+substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING
+BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/NOTICE.md

@@ -0,0 +1,51 @@
+# Provenance of `tools/gen/`, `src/herdr/generated/` and the schema
+
+`@stateforge-labs/herdr-sdk` is built on a **port of a third party's generator**, not on our own original work.
+The chain below is complete from the upstream project to this package. Licence text: [LICENSE](LICENSE).
+
+| | |
+| --- | --- |
+| Upstream | `https://github.com/brooswit-factory/jsHerdrSDK`, commit `e34fd3f2cf32722ed570d1c232c35bdd83eef312` (2026-08-26), paths `scripts/gen/` and `src/` |
+| Published as | `@brooswit/herdr-sdk` 0.1.3 on npm. **Not depended on** by this package |
+| Licence | MIT, declared in the upstream `package.json`. The upstream repository has no LICENSE file |
+| Author | brooswit `<brooswit@gmail.com>` |
+
+## 1. Intermediate port
+
+A private port by the same authors as this package, commit `097adfd662c4818a351c714e4863c1d606726822`.
+Its changes to upstream, as stated in its own `NOTICE.md`:
+
+1. `Bun.file(path).text()` replaced by `readFileSync(path, 'utf8')`.
+2. `.js` import specifiers replaced by `.ts`.
+3. `JSONSchema` is a real recursive interface instead of `Record<string, any>`.
+4. The regular-expression `typeName` scan is a character scan.
+
+## 2. Owner's repairs carried into this package
+
+From the NOTICE of an earlier private copy of the client. These landed in the runtime client:
+
+1. `Connection.destroy()` (hard teardown beside `close()`).
+2. `rpc` takes `signal`, destroys the connection on every settle, and rejects a non-object reply.
+
+## 3. Changes in this package
+
+| File | Change |
+| --- | --- |
+| `tools/gen/schema.ts` | Path parameter: `loadSchema(path)` (the port read a fixed `SCHEMA_PATH`); `GEN_PATHS` replaces the port's `ROOT`, `SCHEMA_PATH` and `OUT_DIR`, and points the output at `src/generated/`. `#gen/*` alias dropped. `constOf` checks its value through an `isString` type guard (TypeScript 7 narrows `typeof` only against a literal, so the P0 form failed `bun run typecheck`). Names (`JS_TYPE`, `SCHEMA_KEY`, `SCHEMA_NAMESPACE`) are `as const` objects. `JSONSchema` gains `default`, `format`, `pattern` and `propertyNames`, for the doc comments. `requestNamespace()` added. The generated header ends "Do not edit." (ASCII full stop, no em dash). |
+| `tools/gen/json-type.ts` | New file, no counterpart in the intermediate port. Holds `JSON_TYPE` and `FORMAT` as `as const` objects and `kindsOf()`, which the port kept inline in `ts-type.ts` and compared against string literals. |
+| `tools/gen/doc-comment.ts` | New file, no counterpart in the intermediate port. Builds one-line JSDoc from `description`, `default` (`@default`), `propertyNames.pattern` (`keys match`) and `format: uint64`, which the port did not emit. Also fixes the port's unescaped `*/` in `emitDefs`: `*/` becomes `* /` and line breaks fold to spaces, for every doc, not only field docs. |
+| `tools/gen/ts-type.ts` | Imports use `./` with `.ts` (`#gen/*` alias dropped). Literal comparisons (`kind === 'string'` and the like) replaced by a `switch` on `JSON_TYPE`; output spellings and separators are named constants. `kindsOf` moved to `json-type.ts`. Field and `$defs` docs go through `schemaDoc()`. The map test for `additionalProperties` is `isSchemaMap` (object, not null). |
+| `tools/gen/merge-defs.ts` | New file, no counterpart in the intermediate port. Replaces the port's hard-coded `SHARED` set in `emit-events.ts` (`AgentStatus`, `PaneScrollInfo`). `mergeDefinitions()` emits a `$def` that several bundles repeat once when the definitions are structurally equal after `$ref` normalisation and key sorting, and throws on a conflict. |
+| `tools/gen/emit-params.ts` | `METHODS` and `Method` moved out to `emit-method-table.ts`; imports `Method` from `./methods.ts`. Adds `MethodParamsCheck`, which fails to compile when a method has no params entry. Bundle and key names from `SCHEMA_NAMESPACE` and `SCHEMA_KEY`, not literals. |
+| `tools/gen/emit-results.ts` | Names (`success_response`, `ResponseResult`, the `Result_` prefix, the `type` key) come from constants. `METHOD_RESULT` is built from the seed by `methodResultTags()` (method to tag only) and checked with `satisfies Partial<Record<Method, ResultTag>>`, where the port imported the record. Imports `Method` from `./methods.ts`. |
+| `tools/gen/emit-errors.ts` | Bundle name from `SCHEMA_NAMESPACE.errorResponse` (the port used the literal `'error_response'`). Otherwise as the port. |
+| `tools/gen/emit-events.ts` | `SHARED` set removed; `mergeDefinitions()` over the `event` and `subscription_event` bundles replaces it, emitting all definitions in one block (the port emitted two blocks with section comments). Bundle names from `SCHEMA_NAMESPACE`. |
+| `tools/gen/emit-index.ts` | New file, no counterpart in the intermediate port. Holds the `index.ts` text that the port's `gen/index.ts` inlined. Re-exports `METHODS` and `Method` from `./methods.ts` rather than `./params.ts`. |
+| `tools/gen/emit-method-table.ts` | New file, no counterpart in the intermediate port. Emits `METHODS` as `{ name, ns }` rows (namespace path split from the dotted name; duplicate names refused) and `Method` derived from it. The class and result columns arrive in phases 1b and 3. |
+| `tools/gen/method-result-map.ts` | The 25 the port rows are the seed as `METHOD_RESULT_SEED`; each row carries a `source` (`RESULT_SOURCE`, all `seed` today). `methodResultTags()` projects them to method to tag. The 25 mappings are unchanged. |
+| `tools/gen/index.ts` | Writes its modules into `src/herdr/generated/` (nested `names/`, `entries/`, `presets/`, `test-data/` since the 2026-11-02 build split), keyed by `renderOutputs()`. The port wrote five into `generated/`, with the index text inline. Bodies come from `renderOutputs()`; `runGenerator({ schemaPath, outDir })` takes paths; the CLI runs under `import.meta.main`. |
+| `package.json` | First version; `herdr` block (protocol 22, schemaVersion 1, testedWith 0.9.5); scripts `capture`, `test:gen`, `check:pins`, `typecheck`; dev pins `@types/node` 22.20.5 and `typescript` 7.0.2 (exact, released at least 14 days before adoption, see HERDR-ADR-0015). |
+| `tsconfig.json` | New. Strict set from the port, `nodenext`, `erasableSyntaxOnly`; includes `gen`, `scripts`, `src`; `test/` excluded until `@types/bun` is adopted. |
+| `tools/scripts/check-pins.ts` | New. Pin gate (exact version, released at least 14 days ago, via `npm view <pkg> time`). |
+| `tools/scripts/capture-schema.ts` | New. Captures `herdr api schema --json` and `herdr --version` into `schema/`. |
+| `LICENSE`, `NOTICE.md`, `.gitignore` | New. MIT licence, this provenance, ignores `node_modules/` and `dist/`. |

package/README.md

@@ -1,3 +1,212 @@
-# Temporary Holding Version
+# @stateforge-labs/herdr-sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A typed client for the whole [herdr](https://herdr.dev) socket API (protocol 22, herdr 0.9.5: 102 methods, 26 event kinds, 27 subscription types), for Bun and Node.
+
+> **Version 0.3.0.** ESM only, Node 22.18+ and Bun. The Promise API, the herdr-core client (`/core`, `/core/test-kit`), the three capability-scoped clients, the fake herdr (`/test-kit`), the schema and drift tools, the tagged errors of `/effect` and the agent skill, all tested against the fake herdr. Every snippet marked "runs" is executed in CI.
+
+## Entry points
+
+| Import | What | Runtime deps |
+|---|---|---|
+| `@stateforge-labs/herdr-sdk` | `connect()`: reads, writes, input, hooks, long-poll, `hold()`; errors; generated types and constants | none |
+| `@stateforge-labs/herdr-sdk/read-only` | `connectReadOnly()`: structure reads only; terminal content on opt-in | none |
+| `@stateforge-labs/herdr-sdk/admin` | `connectAdmin()`: adds destructive, server-control and spawn/execute methods | none |
+| `@stateforge-labs/herdr-sdk/effect` | `toTaggedError`, `EffectErrorTag` and the tagged error types, for mapping the Promise errors into an Effect program | none |
+| `@stateforge-labs/herdr-sdk/test-kit` | `createFakeHerdr()` (tests only) | none |
+| `@stateforge-labs/herdr-sdk/schema` | method table and parameter shapes of the generated API (what a generator, such as an MCP server, builds its tools from) | none |
+| `@stateforge-labs/herdr-sdk/core` | `CoreLink`, `CoreEvents`, the wire parsers and the socket path rule: a client of the herdr-core (`hc`) socket, standalone from the protocol-22 client | none |
+| `@stateforge-labs/herdr-sdk/core/test-kit` | `FakeHcCore`, `setupTest(t)`, `openWorld()` (tests only) | none |
+| `@stateforge-labs/herdr-sdk/drift` | `driftBetween`, `inventoryOf`, `exitCodeFor`: the library behind `herdr-drift`, for your own tooling | none |
+| `herdr-drift` (bin) | compare the committed schema with the installed herdr | none |
+| `herdr-skill` (bin) | print or install the agent skill that ships in `skills/herdr-sdk` | none |
+
+Wire types are `export type` only. Raw strings are accepted by the types, but these docs always use the generated constants (`Method`, `EventKind`, `SubscriptionType`, `AgentStatus`, `WatchKind`).
+
+## Install
+
+```sh
+npm install @stateforge-labs/herdr-sdk
+# or
+bun add @stateforge-labs/herdr-sdk
+```
+
+Versions published from GitHub Actions with npm trusted publishing carry a provenance attestation
+(`npm audit signatures` checks it); 0.3.0 was published by hand and has none. The release tag equals the `package.json` version.
+
+## Footprint
+
+The package ships compiled ESM in `dist/` with declarations (no bundle). A bundler or Node loads only the modules a call reaches: `connect()` does not load the streams until `events.subscribe`, `watch()` or `hold()` is first used.
+
+Measured on 2026-11-02, minified (`bun run check:size`, which builds `dist/` and fails on a budget or a leak):
+
+| What a consumer imports | Bytes |
+|---|---|
+| `@stateforge-labs/herdr-sdk` (every method, `connect()`) | 26,887 |
+| `@stateforge-labs/herdr-sdk/read-only` | 18,691 |
+| `@stateforge-labs/herdr-sdk/admin` | 15,561 |
+| a read-only script that narrows to one method | 17,513 |
+| the streams chunk (`events.subscribe`, `watch`, `hold`), loaded on first use | 7,672 |
+
+The declarations use `AbortSignal` and `AsyncDisposable`. Consumers need `@types/node` 22 or later, or a `lib` that has them (`es2023`, `esnext.disposable`, and `DOM` or `@types/node`). `/test-kit` declarations also import `node:net`.
+
+## 1. A small script (Promise API)
+
+```ts
+import { connect, HerdrError } from "@stateforge-labs/herdr-sdk"
+
+const herdr = await connect() // finds the socket (HERDR_SOCKET, else ~/.config/herdr/herdr.sock), pings, checks protocol 22
+
+const { agents } = await herdr.agent.list({})
+for (const agent of agents) console.log(agent.name, agent.agent_status)
+
+try {
+  await herdr.agent.prompt({ target: "reviewer", text: "run the tests" })
+} catch (error) {
+  if (error instanceof HerdrError) console.error(error.code, error.message)
+  else throw error
+}
+
+herdr.close()
+```
+
+Methods are nested by their dotted name: `herdr.pane.list({})`, `herdr.agent.view.set({...})`. `connect()` has no destructive or server-control methods (`*.close`, `server.stop`, `plugin.link`...); those need `connectAdmin()` from `@stateforge-labs/herdr-sdk/admin`.
+
+A protocol mismatch fails fast; a method the server does not support fails before sending:
+
+```ts
+import { connect, ProtocolMismatchError } from "@stateforge-labs/herdr-sdk"
+
+try {
+  await connect()
+} catch (error) {
+  if (error instanceof ProtocolMismatchError) console.error(`herdr speaks ${error.actual}, this library ${error.expected}`)
+}
+```
+
+## 2. Subscriptions, long-poll and held connections
+
+```ts
+import { connect, SubscriptionType, EventKind, AgentStatus, WatchKind } from "@stateforge-labs/herdr-sdk"
+
+const herdr = await connect({ onCall: ({ method, durationMs, outcome }) => metrics.record(method, durationMs, outcome) })
+
+const subscription = await herdr.events.subscribe([
+  { type: SubscriptionType.PaneCreated },
+  { type: SubscriptionType.PaneClosed },
+  { type: SubscriptionType.PaneAgentStatusChanged, pane_id: "p_1" },
+])
+for await (const frame of subscription) {
+  if (frame.event === EventKind.PaneClosed) break
+}
+subscription.close()
+
+// Long-poll: the timeout is required (herdr would wait forever).
+const done = await herdr.agent.wait({ target: "reviewer", until: [AgentStatus.Done], timeout_ms: 60_000 })
+
+// watch: subscribe, snapshot, replay frames that arrived meanwhile, resubscribe with backoff (1 s doubling to 30 s).
+for await (const change of herdr.watch({ snapshot: () => herdr.session.snapshot({}) })) {
+  if (change.kind === WatchKind.Live) render(change.snapshot)
+  else apply(change.frame)
+}
+
+// Connection-bound methods run on a held connection; closing it ends the title, lease or registration.
+await using held = await herdr.hold()
+await held.client.window_title.set({ title: "review" })
+```
+
+A timeout is not proof that a prompt was not delivered: never resend blindly.
+
+## 3. Read-only and prompt-only clients
+
+```ts
+import { connectReadOnly, Presets } from "@stateforge-labs/herdr-sdk/read-only"
+
+const herdr = await connectReadOnly({ preset: Presets.SessionsReader }) // session.snapshot, agent.list, agent.get, pane.get, pane.list
+const snapshot = await herdr.session.snapshot({})
+// @ts-expect-error a read-only client has no write methods and no generic call()
+await herdr.agent.prompt({ target: "x", text: "y" })
+```
+
+Without options it allows structure reads and long-poll; terminal content (`pane.read`, `agent.read`) needs `{ content: true }`. `{ methods: [Method.AgentList, ...] }` narrows at runtime. `connectPrompt()` adds exactly `agent.prompt`.
+
+## 4. Effect: tagged errors
+
+`toTaggedError(error)` turns an error thrown by the Promise API into a plain object with an Effect-style `_tag`, so an Effect
+program can fail with it (`Effect.tryPromise({ try, catch: toTaggedError })`). The package does not depend on `effect`.
+
+| Promise error | Effect `_tag` | Fields |
+|---|---|---|
+| `HerdrError` | `HerdrRefused` | `method`, `code`, `message` |
+| `HerdrTransportError`, `SubscriptionEnded` | `HerdrUnavailable` | `cause`, `isTimeout` |
+| `ProtocolMismatchError` | `ProtocolMismatch` | `expected`, `actual` |
+| `UnsupportedByServerError` | `HerdrUnsupported` | `method`, `capability` |
+
+Every tagged error also has `message` (the Promise error's message).
+
+## 5. Tests (no live herdr) — runs
+
+```ts
+import { test, expect } from "bun:test"
+import { connect, Method, ResultTag } from "@stateforge-labs/herdr-sdk"
+import { createFakeHerdr } from "@stateforge-labs/herdr-sdk/test-kit"
+
+test("lists agents", async () => {
+  const fake = await createFakeHerdr()
+  fake.reply(Method.AgentList, { type: ResultTag.AgentList, agents: [] })
+  const herdr = await connect({ socketPath: fake.path })
+
+  await herdr.agent.list({})
+
+  expect(fake.receivedMethods()).toEqual([Method.Ping, Method.AgentList])
+  herdr.close()
+  await fake.stop()
+})
+```
+
+The fake runs on `node:net`, answers `ping` and every method you script with `reply`, answers an unscripted method with an `unknown_method` error envelope, and supports `fail`, `silent`, `replySequence`, `push(frame)`, `closeSubscribers()`, `subscriberCount()`, `connectionCount()` and `capabilities`. No test talks to a real herdr.
+
+## Drift
+
+`herdr-drift` ships as a bin. Refreshing the schema and regenerating the client happen in a clone of the repository:
+
+```sh
+bun run capture      # herdr api schema --json > schema/herdr-api.schema.json
+bun run gen          # regenerate src/herdr/generated and docs/api
+herdr-drift          # exit 0 clean, 1 drift, 2 usage, 3 herdr not found
+```
+
+## For coding agents (the skill)
+
+The package ships an Agent Skill, `skills/herdr-sdk/` ([HERDR-ADR-0018](https://github.com/stateforge-labs/herdr-sdk/blob/main/docs/decisions/HERDR-ADR-0018-the-skill-ships-in-the-package.md)): which entry point to pick, recipes, errors, version facts. Its code blocks are type-checked and run against the fake in the repository's `test/skill/`.
+
+```sh
+herdr-skill install              # copies it to .claude/skills/herdr-sdk (or: herdr-skill install ~/.claude/skills)
+herdr-skill print                # prints SKILL.md, for agents that take a prompt rather than a folder
+```
+
+Claude Code does not look inside `node_modules`, so `install` copies the skill to a skills directory. For other agents, add this to the project's `AGENTS.md`:
+
+> Code that uses `@stateforge-labs/herdr-sdk`: read `node_modules/@stateforge-labs/herdr-sdk/skills/herdr-sdk/SKILL.md` first.
+
+## Using it from your own domain
+
+The library conforms to herdr's wire vocabulary. Keep your own domain language behind your own port, and let one adapter file import `@stateforge-labs/herdr-sdk`. `tools/scripts/check-layers.ts` enforces the library's own layers; the one-adapter rule for consumers is a convention. Snapshot before you subscribe, because a subscription delivers changes, not the present. `watch()` does this for you (see the [decision records](https://github.com/stateforge-labs/herdr-sdk/tree/main/docs/decisions)).
+
+## Repository layout
+
+This section describes the [GitHub repository](https://github.com/stateforge-labs/herdr-sdk); the npm package ships only `dist/`, the bins, the skill, the schema and the API docs.
+
+One folder per product ([HERDR-ADR-0021](https://github.com/stateforge-labs/herdr-sdk/blob/main/docs/decisions/HERDR-ADR-0021-one-folder-per-product.md)); the entry files at the top of `src/` are the published subpaths.
+
+| Folder | What it is |
+| --- | --- |
+| `src/herdr/` | The herdr server client (protocol 22): `errors.ts` (every error it throws), `wire/`, `client/` (one module per feature: `connect`, `scoped`, `subscribe`, `watch`, `watch-pane-set`, `held`, `long-poll`, and `streams`, loaded on first use), `generated/` (output of `tools/gen/`), `effect/`, `test-kit/` |
+| `src/core/` | The herdr-core client (`./core`): `errors.ts` (every failure it returns), `kernel.ts` (its value types), `wire`, `link`, `events`, `backoff`, `constants`; its fake core in `test-kit/` (`./core/test-kit`) |
+| `src/drift/` | The schema-drift tool behind `herdr-drift`: `schema`, `diff`, `cli`, `constants`, `types` |
+| `test/` | Mirrors `src/` (`test/herdr/`, `test/core/`, `test/drift/`), plus `test/tools/`, `integration/` and `types/` |
+| `tools/` | Build time only, never published: `gen/` (the generator), `scripts/` (gates, capture, build helpers), `rules/` (the layer rule) |
+| `bin/`, `skills/`, `schema/`, `docs/` | The bins, the agent skill, the captured schema, the docs and decisions |
+
+## Licence
+
+MIT. Derived from [brooswit-factory/jsHerdrSDK](https://github.com/brooswit-factory/jsHerdrSDK) (e34fd3f) through an intermediate private port (097adfd); see `NOTICE.md`.

package/bin/herdr-drift.js

@@ -0,0 +1,14 @@
+#!/usr/bin/env node
+// Role: the herdr-drift bin (package bin, plain JS so Node runs it from node_modules): the process I/O of the drift CLI. It runs the herdr CLI and sets the exit code; the logic is dist/drift/cli.js.
+// Informs HERDR-ADR-0009 (exit codes 0/1/2/3), HERDR-ADR-0008 (the herdr CLI runs here only, never the socket) and HERDR-ADR-0012 (the package runs compiled JavaScript, not .ts).
+import { execFileSync } from 'node:child_process';
+import { HerdrCall } from '../dist/drift/constants.js';
+import { runDriftCli } from '../dist/drift/cli.js';
+
+const spawnHerdr = (binary) => (args) => execFileSync(binary, [...args], {
+  encoding: 'utf8',
+  timeout: HerdrCall.TimeoutMs,
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+
+process.exitCode = await runDriftCli(process.argv.slice(2), spawnHerdr);

package/bin/herdr-skill.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// Role: the herdr-skill bin: prints or installs the agent skill that ships in this package (skills/herdr-sdk), so an agent can load it without knowing where node_modules is.
+// Informs HERDR-ADR-0018 (the skill ships in the package; Claude Code does not discover node_modules, so `install` copies it into a skills directory) and the hc `--skill` convention.
+import { cpSync, existsSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const SKILL_NAME = 'herdr-sdk';
+const SKILL_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', 'skills', SKILL_NAME);
+const DEFAULT_TARGET = join('.claude', 'skills');
+const USAGE = `usage: herdr-skill <command>
+  print              print SKILL.md to stdout
+  path               print the directory of the skill inside this package
+  install [skills-dir]   copy the skill to <skills-dir>/${SKILL_NAME} (default ${DEFAULT_TARGET}); an existing copy is replaced
+exit: 0 ok, 2 usage`;
+
+function run(args) {
+  const [command, target] = args;
+  if (command === 'print') {
+    process.stdout.write(readFileSync(join(SKILL_DIR, 'SKILL.md'), 'utf8'));
+    return 0;
+  }
+  if (command === 'path') {
+    console.log(SKILL_DIR);
+    return 0;
+  }
+  if (command === 'install') {
+    const destination = resolve(target ?? DEFAULT_TARGET, SKILL_NAME);
+    const replaced = existsSync(destination);
+    cpSync(SKILL_DIR, destination, { recursive: true, force: true });
+    console.log(`${replaced ? 'replaced' : 'installed'} ${destination}`);
+    return 0;
+  }
+  console.error(USAGE);
+  return 2;
+}
+
+process.exitCode = run(process.argv.slice(2));

package/dist/admin.d.ts

@@ -0,0 +1,2 @@
+export { connectAdmin } from './herdr/client/scoped.js';
+export type { AdminClient } from './herdr/client/types.js';

package/dist/admin.js

@@ -0,0 +1,3 @@
+// Role: the /admin entry: connectAdmin() with destructive, server-control and spawn/execute methods.
+// Informs HERDR-ADR-0003, HERDR-ADR-0005 and HERDR-ADR-0017; edited only by the integration step.
+export { connectAdmin } from './herdr/client/scoped.js';

package/dist/constants.d.ts

@@ -0,0 +1,236 @@
+import { SubscriptionType } from './herdr/generated/index.js';
+import type { ServerCapabilities } from './herdr/generated/results.js';
+export { TOKEN_NAME_PATTERN } from './herdr/generated/names/token-name-pattern.js';
+export declare const HerdrEnv: {
+    readonly Socket: 'HERDR_SOCKET';
+    readonly Home: 'HOME';
+    readonly Live: 'HERDR_LIVE';
+};
+export declare const SocketPathPart: {
+    readonly ConfigDir: '.config';
+    readonly HerdrDir: 'herdr';
+    readonly SocketFile: 'herdr.sock';
+};
+export declare const Timeout: {
+    readonly DefaultMs: 10000;
+    readonly LongPollMarginMs: 5000;
+};
+export declare const Backoff: {
+    readonly InitialMs: 1000;
+    readonly MaxMs: 30000;
+    readonly Factor: 2;
+    readonly StableResetMs: 60000;
+};
+export declare const ProtocolPolicy: {
+    readonly Exact: 'exact';
+    readonly Minimum: 'minimum';
+};
+export type ProtocolPolicy = (typeof ProtocolPolicy)[keyof typeof ProtocolPolicy];
+export declare const Overflow: {
+    readonly DropOldest: 'drop-oldest';
+    readonly Fail: 'fail';
+};
+export type Overflow = (typeof Overflow)[keyof typeof Overflow];
+export declare const WatchKind: {
+    readonly Live: 'live';
+    readonly Frame: 'frame';
+};
+export type WatchKind = (typeof WatchKind)[keyof typeof WatchKind];
+export declare const Presets: {
+    readonly SessionsReader: 'SessionsReader';
+};
+export type Preset = (typeof Presets)[keyof typeof Presets];
+export declare const SUBSCRIBE_ID_PREFIX = "sub";
+export declare const ErrorText: {
+    readonly NoAck: (ms: number) => string;
+    readonly Unavailable: (method: string, what: string) => string;
+    readonly NoResponse: (method: string, ms: number) => string;
+    readonly Aborted: (method: string) => string;
+    readonly Unparseable: (method: string) => string;
+    readonly ClosedBeforeResponse: (method: string) => string;
+    readonly ClientClosed: (method: string) => string;
+    readonly SocketError: (method: string) => string;
+    readonly CannotConnect: (path: string) => string;
+    readonly NoSocket: (path: string) => string;
+    readonly ProtocolMismatch: (expected: number, actual: number) => string;
+    readonly Unsupported: (method: string, capability: string) => string;
+    readonly Refused: (method: string, message: string, code: string) => string;
+    readonly SubscriptionEnded: (method: string) => string;
+    readonly NotImplemented: (what: string, lane: string) => string;
+    readonly NotAllowed: (method: string) => string;
+};
+export declare const ErrorName: {
+    readonly Herdr: 'HerdrError';
+    readonly Transport: 'HerdrTransportError';
+    readonly ProtocolMismatch: 'ProtocolMismatchError';
+    readonly UnsupportedByServer: 'UnsupportedByServerError';
+    readonly SubscriptionEnded: 'SubscriptionEnded';
+    readonly NotImplemented: 'NotImplementedError';
+    readonly MalformedSchema: 'MalformedSchemaError';
+    readonly UnsupportedWatch: 'UnsupportedWatchError';
+};
+export declare const WireField: {
+    readonly Id: 'id';
+    readonly Method: 'method';
+    readonly Params: 'params';
+    readonly Result: 'result';
+    readonly Error: 'error';
+    readonly Code: 'code';
+    readonly Message: 'message';
+    readonly Type: 'type';
+    readonly Protocol: 'protocol';
+    readonly Version: 'version';
+    readonly Capabilities: 'capabilities';
+    readonly Event: 'event';
+};
+export declare const REQUEST_ID_PREFIX = "sdk";
+export declare const EMPTY_REPLY_ID = "";
+export declare const LINE_SEPARATOR = "\n";
+export declare const TEXT_ENCODING: 'utf8';
+export declare const CallOutcome: {
+    readonly Answered: 'answered';
+    readonly Refused: 'refused';
+    readonly Transport: 'transport';
+};
+export type CallOutcome = (typeof CallOutcome)[keyof typeof CallOutcome];
+export declare const TypeofTag: {
+    readonly Object: 'object';
+    readonly String: 'string';
+};
+export declare const Fake: {
+    readonly DirPrefix: 'herdr-fake-';
+    readonly SocketFile: 'herdr.sock';
+    readonly Version: '0.9.5-fake';
+    readonly UnknownMethodCode: 'unknown_method';
+    readonly InvalidRequestCode: 'invalid_request';
+    readonly SplitAckDelayMs: 5;
+};
+export declare const FakeText: {
+    readonly UnknownMethod: (method: string) => string;
+    readonly InvalidRequest: 'unparseable request';
+};
+export declare const DEFAULT_CAPABILITIES: ServerCapabilities;
+export declare const AnswerKind: {
+    readonly Silent: 'silent';
+    readonly Raw: 'raw';
+    readonly Envelope: 'envelope';
+};
+export type AnswerKind = (typeof AnswerKind)[keyof typeof AnswerKind];
+export declare const ServedState: {
+    readonly Fresh: 'fresh';
+    readonly Answered: 'answered';
+    readonly Subscriber: 'subscriber';
+    readonly Held: 'held';
+};
+export type ServedState = (typeof ServedState)[keyof typeof ServedState];
+export declare const UNKNOWN_EVENT: '@stateforge-labs/herdr-sdk:unknown-event';
+export declare const PaneSetKind: {
+    readonly Added: 'added';
+    readonly Removed: 'removed';
+    readonly Frame: 'frame';
+};
+export type PaneSetKind = (typeof PaneSetKind)[keyof typeof PaneSetKind];
+export declare const PER_PANE_SUBSCRIPTION_TYPES: readonly ["pane.output_matched", "pane.agent_status_changed", "pane.scroll_changed"];
+export declare const GLOBAL_SUBSCRIPTION_TYPES: readonly SubscriptionType[];
+export declare const DriftExitCode: {
+    readonly Clean: 0;
+    readonly Drift: 1;
+    readonly Usage: 2;
+    readonly NotCovered: 3;
+};
+export type DriftExitCode = (typeof DriftExitCode)[keyof typeof DriftExitCode];
+export declare const SchemaReadKind: {
+    readonly Found: 'found';
+    readonly NotFound: 'not-found';
+    readonly Unreadable: 'unreadable';
+};
+export type SchemaReadKind = (typeof SchemaReadKind)[keyof typeof SchemaReadKind];
+export declare const DriftOutcomeKind: {
+    readonly Usage: 'usage';
+    readonly NotCovered: 'not-covered';
+    readonly Report: 'report';
+};
+export type DriftOutcomeKind = (typeof DriftOutcomeKind)[keyof typeof DriftOutcomeKind];
+export declare const EffectErrorTag: {
+    readonly Refused: 'HerdrRefused';
+    readonly Unavailable: 'HerdrUnavailable';
+    readonly ProtocolMismatch: 'ProtocolMismatch';
+    readonly Unsupported: 'HerdrUnsupported';
+};
+export type EffectErrorTag = (typeof EffectErrorTag)[keyof typeof EffectErrorTag];
+export declare const WireFact: {
+    readonly W1CloseAfterResponse: 'W1';
+    readonly W2AckThenStream: 'W2';
+    readonly W3EmptyIdOnUnparseable: 'W3';
+    readonly W4SchemaOverSocketIsEmpty: 'W4';
+    readonly W5NoHistoryReplay: 'W5';
+    readonly W6PerPaneNeedsPaneId: 'W6';
+};
+export type WireFact = (typeof WireFact)[keyof typeof WireFact];
+export declare const Lane: {
+    readonly P2a: 'P2a';
+    readonly P2b: 'P2b';
+    readonly P3: 'P3';
+    readonly P4a: 'P4a';
+    readonly P4b: 'P4b';
+    readonly P5a: 'P5a';
+    readonly P5c: 'P5c';
+    readonly P6a: 'P6a';
+};
+export type Lane = (typeof Lane)[keyof typeof Lane];
+export declare const EntryKey: {
+    readonly client: 'client';
+    readonly admin: 'admin';
+    readonly prompt: 'prompt';
+    readonly readOnly: 'readOnly';
+    readonly readOnlyContent: 'readOnlyContent';
+    readonly held: 'held';
+};
+export type EntryKey = (typeof EntryKey)[keyof typeof EntryKey];
+export declare const METHOD_SEPARATOR = ".";
+export declare const TreeKey: {
+    readonly Events: 'events';
+    readonly Subscribe: 'subscribe';
+};
+export declare const TypeofKind: {
+    readonly Function: 'function';
+    readonly Object: 'object';
+};
+export declare const WatchText: {
+    readonly ReplayOverflow: (max: number) => string;
+    readonly OutputMatchUnsupported: 'watchPaneSet does not subscribe to pane.output_matched: its match and source are not options yet (HERDR-ADR-0016 open issue 8)';
+};
+export declare const HeldText: {
+    readonly Ended: (method: string) => string;
+};
+export declare const PANE_LIFECYCLE_SUBSCRIPTION_TYPES: readonly ["pane.created", "pane.closed"];
+export declare const FakeErrorCode: {
+    readonly InvalidParams: 'invalid_params';
+};
+export declare const FakeCheckText: {
+    readonly NotAnObject: (method: string) => string;
+    readonly MissingField: (method: string, field: string) => string;
+    readonly WrongKind: (method: string, field: string) => string;
+    readonly NotInEnum: (method: string, field: string) => string;
+    readonly KeyNotAllowed: (method: string, field: string) => string;
+    readonly NeedsPaneId: (type: string) => string;
+};
+export declare const TypeofValue: {
+    readonly Number: 'number';
+    readonly Boolean: 'boolean';
+};
+export declare const EMPTY_SCHEMA_RESULT: Readonly<Record<string, never>>;
+export declare const SpecField: {
+    readonly Subscriptions: 'subscriptions';
+    readonly PaneId: 'pane_id';
+};
+export declare const FakeMethod: {
+    readonly ApiSchema: 'api.schema';
+};
+export declare const NameSeparator: {
+    readonly Event: '_';
+    readonly Subscription: '.';
+};
+export declare const EffectFallbackMessage: {
+    readonly UnknownError: 'unknown herdr error';
+};