@knpkv/herdr-connect 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 knpkv
+
+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/README.md

@@ -0,0 +1,11 @@
+# `@knpkv/herdr-connect`
+
+Fleet agent directory and authenticated Herdr terminal control.
+
+The directory combines the local inventory with peer `/v1/connect/agents/local` responses. Peer requests time out after 1.5 seconds and run with bounded concurrency. An offline, unavailable, timed-out, or malformed peer becomes a typed partial failure; healthy agents remain usable.
+
+The terminal connector resolves an opaque agent ID against the current local inventory, starts `herdr terminal session control`, streams Schema-decoded frames, and writes bounded input, resize, scroll, and release commands. Its session is scoped, so interruption releases or kills the child instead of leaving an attach process behind.
+
+Browser consumers can import `@knpkv/herdr-connect/client` for the mounting entry, `@knpkv/herdr-connect/surface` for the embeddable state and view, and `@knpkv/herdr-connect/styles.css` for package-owned styles. Exact `host` plus stable `agent` query parameters select that room. The relationship store keys metadata by exact host and stable agent ID. Trusted live inventory may replace a stored parent only for the same host, stable agent ID, and pane with a strictly newer observation; durable, stale, equal, or pane-changing observations cannot reparent an agent. The view renders reported roots and parent relations; missing, cross-host, cyclic, or ambiguous ownership stays explicit and is never guessed.
+
+Browser contracts are available through `@knpkv/herdr-connect/model`; browser subpaths do not pull SQLite or Node process code into the bundle.

package/dist/activity-store.d.ts

@@ -0,0 +1,11 @@
+import { Effect, FileSystem, Path } from "effect";
+import { TerminalTransportError } from "./errors.js";
+export declare class AgentActivityStore {
+    #private;
+    readonly path: string;
+    private constructor();
+    static readonly open: (path: string) => Effect.Effect<AgentActivityStore, TerminalTransportError, FileSystem.FileSystem | Path.Path>;
+    readonly observe: (this: AgentActivityStore, host: string, agentId: string, revision: number, observedAt: number) => Effect.Effect<number, TerminalTransportError, never>;
+    close(): void;
+}
+//# sourceMappingURL=activity-store.d.ts.map

package/dist/activity-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-store.d.ts","sourceRoot":"","sources":["../src/activity-store.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,IAAI,EAAU,MAAM,QAAQ,CAAA;AAEzD,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAA;AAQpD,qBAAa,kBAAkB;;IAE7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,OAAO,eA2BN;IAED,MAAM,CAAC,QAAQ,CAAC,IAAI,iHAclB;IAEF,QAAQ,CAAC,OAAO,0JAqCd;IAEF,KAAK,IAAI,IAAI,CAEZ;CACF"}

package/dist/activity-store.js

@@ -0,0 +1,76 @@
+import { Effect, FileSystem, Path, Schema } from "effect";
+import { DatabaseSync } from "node:sqlite";
+import { TerminalTransportError } from "./errors.js";
+const ActivityRow = Schema.Struct({ last_activity_at: Schema.Number });
+const TableColumn = Schema.Struct({ name: Schema.String });
+const storeError = (operation) => (cause) => new TerminalTransportError({ cause, detail: String(cause), operation });
+export class AgentActivityStore {
+    #database;
+    path;
+    constructor(path) {
+        this.path = path;
+        this.#database = new DatabaseSync(path);
+        try {
+            this.#database.exec(`
+        PRAGMA journal_mode = WAL;
+        CREATE TABLE IF NOT EXISTS agent_activity (
+          host TEXT COLLATE NOCASE NOT NULL,
+          agent_id TEXT NOT NULL,
+          revision INTEGER NOT NULL,
+          last_activity_at INTEGER NOT NULL,
+          observed_at INTEGER NOT NULL DEFAULT 0,
+          PRIMARY KEY (host, agent_id)
+        );
+      `);
+            const columns = Schema.decodeUnknownSync(Schema.Array(TableColumn))(this.#database.prepare("PRAGMA table_info(agent_activity)").all());
+            if (!columns.some(({ name }) => name === "observed_at")) {
+                this.#database.exec("ALTER TABLE agent_activity ADD COLUMN observed_at INTEGER NOT NULL DEFAULT 0");
+            }
+        }
+        catch (error) {
+            this.#database.close();
+            throw error;
+        }
+    }
+    static open = Effect.fn("AgentActivityStore.open")(function* (path) {
+        const fileSystem = yield* FileSystem.FileSystem;
+        const paths = yield* Path.Path;
+        const directory = paths.dirname(path);
+        yield* fileSystem.makeDirectory(directory, { recursive: true, mode: 0o700 }).pipe(Effect.mapError(storeError("activity.openDirectory")));
+        yield* fileSystem.chmod(directory, 0o700).pipe(Effect.mapError(storeError("activity.secureDirectory")));
+        return yield* Effect.try({
+            try: () => new AgentActivityStore(path),
+            catch: storeError("activity.openDatabase")
+        });
+    });
+    observe = Effect.fn("AgentActivityStore.observe")(function* (host, agentId, revision, observedAt) {
+        const normalizedHost = host.toLowerCase();
+        const row = yield* Effect.try({
+            try: () => this.#database
+                .prepare(`INSERT INTO agent_activity (host, agent_id, revision, last_activity_at, observed_at)
+             VALUES (?, ?, ?, ?, ?)
+             ON CONFLICT(host, agent_id) DO UPDATE SET
+               revision = CASE
+                 WHEN excluded.observed_at >= agent_activity.observed_at
+                 THEN excluded.revision
+                 ELSE agent_activity.revision
+               END,
+               last_activity_at = CASE
+                 WHEN excluded.observed_at < agent_activity.observed_at
+                 THEN agent_activity.last_activity_at
+                 WHEN agent_activity.revision = excluded.revision
+                 THEN agent_activity.last_activity_at
+                 ELSE excluded.last_activity_at
+               END,
+               observed_at = MAX(agent_activity.observed_at, excluded.observed_at)
+             RETURNING last_activity_at`)
+                .get(normalizedHost, agentId, revision, observedAt, observedAt),
+            catch: storeError("activity.observe")
+        });
+        return yield* Schema.decodeUnknownEffect(ActivityRow)(row).pipe(Effect.mapError(storeError("activity.decode")), Effect.map(({ last_activity_at }) => last_activity_at));
+    });
+    close() {
+        this.#database.close();
+    }
+}
+//# sourceMappingURL=activity-store.js.map

package/dist/activity-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-store.js","sourceRoot":"","sources":["../src/activity-store.ts"],"names":[],"mappings":"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"}

package/dist/client-entry.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=client-entry.d.ts.map

package/dist/client-entry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-entry.d.ts","sourceRoot":"","sources":["../src/client-entry.tsx"],"names":[],"mappings":""}

package/dist/client-entry.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { RegistryProvider } from "@effect/atom-react";
+import { createRoot } from "react-dom/client";
+import { ConnectSurface, makeConnectAtoms } from "./client.js";
+import { ConnectBootstrapError } from "./errors.js";
+const root = document.querySelector("#fleet-connect-root");
+if (root === null) {
+    throw new ConnectBootstrapError({ detail: "Connect root is missing" });
+}
+createRoot(root).render(_jsx(RegistryProvider, { children: _jsx(ConnectSurface, { atoms: makeConnectAtoms() }) }));
+//# sourceMappingURL=client-entry.js.map

package/dist/client-entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client-entry.js","sourceRoot":"","sources":["../src/client-entry.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAA;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAC7C,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAA;AAC9D,OAAO,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAA;AAEnD,MAAM,IAAI,GAAG,QAAQ,CAAC,aAAa,CAAc,qBAAqB,CAAC,CAAA;AACvE,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;IAClB,MAAM,IAAI,qBAAqB,CAAC,EAAE,MAAM,EAAE,yBAAyB,EAAE,CAAC,CAAA;AACxE,CAAC;AAED,UAAU,CAAC,IAAI,CAAC,CAAC,MAAM,CACrB,KAAC,gBAAgB,cACf,KAAC,cAAc,IAAC,KAAK,EAAE,gBAAgB,EAAE,GAAI,GAC5B,CACpB,CAAA"}

package/dist/client.d.ts

@@ -0,0 +1,86 @@
+import { Cause, Schema } from "effect";
+import * as AsyncResult from "effect/unstable/reactivity/AsyncResult";
+import * as Atom from "effect/unstable/reactivity/Atom";
+import { type ReactNode } from "react";
+import { type ConnectAgent } from "./model.js";
+import { type AgentActivityFilter } from "./view.js";
+declare const ConnectNetworkError_base: Schema.Class<ConnectNetworkError, Schema.TaggedStruct<"ConnectNetworkError", {
+    readonly detail: Schema.String;
+}>, Cause.YieldableError>;
+declare class ConnectNetworkError extends ConnectNetworkError_base {
+}
+declare const ConnectStatusError_base: Schema.Class<ConnectStatusError, Schema.TaggedStruct<"ConnectStatusError", {
+    readonly status: Schema.Number;
+}>, Cause.YieldableError>;
+declare class ConnectStatusError extends ConnectStatusError_base {
+}
+declare const ConnectProtocolError_base: Schema.Class<ConnectProtocolError, Schema.TaggedStruct<"ConnectProtocolError", {
+    readonly detail: Schema.String;
+    readonly cause: Schema.Defect;
+}>, Cause.YieldableError>;
+declare class ConnectProtocolError extends ConnectProtocolError_base {
+}
+declare const ConnectPreferenceError_base: Schema.Class<ConnectPreferenceError, Schema.TaggedStruct<"ConnectPreferenceError", {
+    readonly operation: Schema.String;
+    readonly cause: Schema.Defect;
+}>, Cause.YieldableError>;
+declare class ConnectPreferenceError extends ConnectPreferenceError_base {
+}
+type ConnectionState = {
+    readonly _tag: "idle";
+} | {
+    readonly _tag: "connecting";
+    readonly agent: ConnectAgent;
+} | {
+    readonly _tag: "connected";
+    readonly agent: ConnectAgent;
+} | {
+    readonly _tag: "closed";
+    readonly agent: ConnectAgent;
+} | {
+    readonly _tag: "failed";
+    readonly agent: ConnectAgent;
+    readonly detail: string;
+};
+type ConnectionRequest = {
+    readonly agent: ConnectAgent;
+    readonly id: number;
+};
+export declare const makeConnectAtoms: () => {
+    activityFilter: Atom.Writable<AgentActivityFilter, AgentActivityFilter>;
+    agents: Atom.Atom<AsyncResult.AsyncResult<{
+        readonly agents: readonly {
+            readonly id: string;
+            readonly host: string;
+            readonly name: string;
+            readonly kind: string;
+            readonly state: string;
+            readonly work: string;
+            readonly lastActivityAt: number;
+            readonly relationship?: {
+                readonly parentAgentId: string;
+                readonly relation: "delegated" | "pair" | "review";
+            };
+        }[];
+        readonly failures: readonly {
+            readonly host: string;
+            readonly reason: "invalid_response" | "offline" | "request_failed" | "timeout" | "unavailable";
+        }[];
+    }, ConnectNetworkError | ConnectProtocolError | ConnectStatusError>>;
+    agentsPoll: Atom.Atom<AsyncResult.AsyncResult<number, never>>;
+    connection: Atom.Writable<ConnectionState, ConnectionState>;
+    connectionRequest: Atom.Writable<ConnectionRequest | null, ConnectionRequest | null>;
+    hostFilter: Atom.Writable<string | null, string | null>;
+    preference: Atom.Atom<AsyncResult.AsyncResult<string | null, ConnectPreferenceError>>;
+    preferenceError: Atom.Writable<string | null, string | null>;
+    query: Atom.Writable<string, string>;
+    selectedKey: Atom.Writable<string | null, string | null>;
+};
+export type ConnectAtoms = ReturnType<typeof makeConnectAtoms>;
+export declare const ConnectSurface: ({ atoms, embedded, roomFooter }: {
+    readonly atoms: ConnectAtoms;
+    readonly embedded?: boolean;
+    readonly roomFooter?: ReactNode;
+}) => import("react").JSX.Element;
+export {};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.tsx"],"names":[],"mappings":"AAIA,OAAO,EAAE,KAAK,EAAmC,MAAM,EAAE,MAAM,QAAQ,CAAA;AACvE,OAAO,KAAK,WAAW,MAAM,wCAAwC,CAAA;AACrE,OAAO,KAAK,IAAI,MAAM,iCAAiC,CAAA;AAIvD,OAAO,EAAyC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAA;AAE7E,OAAO,EACL,KAAK,YAAY,EAMlB,MAAM,YAAY,CAAA;AAOnB,OAAO,EAAqD,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAA;;;;AAOvG,cAAM,mBAAoB,SAAQ,wBAEhC;CAAG;;;;AAEL,cAAM,kBAAmB,SAAQ,uBAE/B;CAAG;;;;;AAEL,cAAM,oBAAqB,SAAQ,yBAGjC;CAAG;;;;;AAEL,cAAM,sBAAuB,SAAQ,2BAGnC;CAAG;AAML,KAAK,eAAe,GAChB;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAC7D;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GAC5D;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;CAAE,GACzD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;CACxB,CAAA;AAEL,KAAK,iBAAiB,GAAG;IACvB,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CACpB,CAAA;AAwGD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAc5B,CAAA;AAED,MAAM,MAAM,YAAY,GAAG,UAAU,CAAC,OAAO,gBAAgB,CAAC,CAAA;AA4O9D,eAAO,MAAM,cAAc,oCAIxB;IACD,QAAQ,CAAC,KAAK,EAAE,YAAY,CAAA;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,SAAS,CAAA;CAChC,gCAuPA,CAAA"}