room-kit 1.0.2 → 1.0.6

package/harness-rules.toml

@@ -0,0 +1,177 @@
+# harness-rules.toml — policy for what the AI agent can do in this project.
+# Commit this file to your repository. harness-hat reads it but never pushes
+# changes back during workspace sync.
+#
+# Agents/LLMs are not permitted to edit this file directly. Harness Hat monitors
+# this policy file and will notify the user if an agent attempts to modify it.
+#
+# Preferred place for *human/LLM instructions*:
+# llm_instructions = """
+# Environment:
+# - You are operating inside a Linux Docker container managed by harness-hat.
+# - Your workspace is mounted into the container; edits usually persist to the host.
+# - Do not assume host tools, credentials, or services are directly available in the container.
+#
+# Host-side commands:
+# - Use `hostdo ...` when you need host-side build/package tooling such as cargo,
+#   npm, pnpm, yarn, go, make, pytest, or similar commands.
+# - Examples: `hostdo cargo test`, `hostdo npm install`, `hostdo go test ./...`.
+# - Only use `hostdo --image <docker-image> ...` when the user explicitly asks
+#   you to run against a Docker image or containerized runner.
+# - Use `hostdo --timeout <seconds> ...` when the user explicitly asks for a
+#   longer or shorter host-side command timeout, or when a command exits before
+#   finishing and clearly needs more time than the default rule allows.
+# - Examples: `hostdo --timeout 120 cargo test`,
+#   `hostdo --timeout 1800 npm run build`.
+# - `hostdo --image` runs a command in a short-lived Docker runner instead of
+#   directly on the host.
+# - Examples: `hostdo --image node:20 npm test`,
+#   `hostdo --image rust:1.88 cargo test`.
+# - `hostdo` requests are policy checked against the `[hostdo]` rules below and may
+#   prompt the developer.
+# - Prefer existing auto-approved `hostdo` commands or `hostdo.command_aliases`
+#   before asking for a new host command approval.
+#
+# Subagents:
+# - Run `agentctl list` first to see the configured subagent profiles available
+#   in this environment. Use the profile name from the first column; do not
+#   guess hardcoded names such as `codex`, `claude`, or `qwen`.
+# - Use `agentctl spawn <profile> [--name <child>]` to start a same-workspace
+#   subagent from one of those configured container profiles.
+# - After spawning, give the child a task with
+#   `agentctl send <child> "task prompt" --enter`.
+# - A typical sequence is `agentctl list`, `agentctl spawn <profile> --name review`,
+#   `agentctl status review`, `agentctl tail review --rows 30`, then
+#   `agentctl send review "inspect the failing test" --enter`.
+# - Use `agentctl spawn-many <profile> <count> --prefix <name>` for larger
+#   batches; launches are paced by `[agentctl].spawn_delay_ms` and never below
+#   100ms between spawn requests.
+# - Codex subagent launches additionally wait for the previous Codex launch to
+#   fail MCP startup, clear MCP startup, sit waiting without MCP diagnostics for
+#   a short stable window, or reach the 35s diagnostic timeout.
+# - `[agentctl].max_subagents` caps live descendants under a single top-level
+#   agent, including subagents, sub-subagents, and deeper descendants.
+# - Use `agentctl status <child>`, `agentctl tail <child> --rows 30`,
+#   `agentctl tail <child> --all`, `agentctl send <child> "text" --enter`,
+#   `agentctl send <child> --key enter`, and `agentctl stop <child>` to inspect
+#   and control direct child agents.
+# - If `agentctl list` reports `image-missing`, the profile exists but its
+#   Docker image must be built or pulled before `agentctl spawn` will work.
+# - Subagent names are scoped to the parent that created them; duplicate names
+#   may exist elsewhere in the tree.
+#
+# Container lifecycle:
+# - Use `killme` only when the user explicitly asks you to end this container.
+# """
+#
+# ── Hostdo (host-side command execution) ─────────────────────────────────────
+#
+# default_policy: what happens when a command doesn't match any rule below.
+#   auto   — run without prompting (use with caution)
+#   prompt — ask the developer in the TUI (default)
+#   deny   — reject silently
+#
+# Passthrough command (exact argv match, auto-approved):
+#   [[hostdo.commands]]
+#   argv = ["cargo", "test"] # run inside container with `hostdo cargo test`
+#   cwd = "$WORKSPACE"         # execution cwd only, not part of approval matching
+#   timeout_secs = 60
+#   approval_mode = "auto"
+#
+# Short-lived Docker runner (exact argv + image match, auto-approved):
+#   [[hostdo.commands]]
+#   argv = ["npm", "test"]     # run with `hostdo --image node:20 npm test`
+#   image = "node:20"
+#   cwd = "$WORKSPACE"
+#   timeout_secs = 60
+#   approval_mode = "auto"
+#
+# Command alias (agent sends `hostdo tests`, expands server-side):
+#   [hostdo.command_aliases]
+#   tests = "cargo test" # run inside container with `hostdo test`
+#   build = { cmd = "cargo build --release", cwd = "$WORKSPACE" }
+#
+# $WORKSPACE = workspace path on the host.
+#
+# ── Agentctl helper defaults ────────────────────────────────────────────────
+#
+# `agentctl spawn` and `spawn-many` read this value from the workspace rules file
+# when `--delay-ms` is omitted. The effective delay is clamped to at least 100ms.
+# `max_subagents` limits live descendants under a single top-level agent.
+#   [agentctl]
+#   spawn_delay_ms = 500
+#   max_subagents = 10
+
+# ── Network (HTTP/HTTPS proxy policy) ────────────────────────────────────────
+#
+# Coder-style network rules. Deny matches win over allow matches; if no rule
+# matches, request is prompted.
+# Rule format:
+#   method=GET,POST domain=api.example.com path=/v1/*,/health port=443,8443
+#
+# Use [network].allowlist for permanent allows and [network].denylist for
+# permanent denies.
+#
+# Domain matching:
+# - `domain=example.com` exact only
+# - `domain=*.example.com` subdomains only (not the apex)
+#
+# Path matching:
+# - exact (`/v1/users`)
+# - wildcard (`/v1/*`)
+#
+# Port matching:
+# - omitted port matches normal HTTP/HTTPS requests on any port
+# - CONNECT allow rules without `port=` only auto-approve port 443
+# - raw CONNECT to other ports requires an explicit `port=...` allow rule
+
+version = 1
+
+[agentctl]
+spawn_delay_ms = 500
+max_subagents = 10
+
+[hostdo]
+default_policy = "prompt"
+commands = []
+
+[hostdo.command_aliases.yarn_test]
+cmd = "yarn test"
+cwd = "$WORKSPACE"
+
+[hostdo.command_aliases.install]
+cmd = "npm install"
+cwd = "$WORKSPACE"
+
+[hostdo.command_aliases.pnpm_test]
+cmd = "pnpm test"
+cwd = "$WORKSPACE"
+
+[hostdo.command_aliases.build]
+cmd = "npm run build"
+cwd = "$WORKSPACE"
+
+[hostdo.command_aliases.lint]
+cmd = "npm run lint"
+cwd = "$WORKSPACE"
+
+[hostdo.command_aliases.test]
+cmd = "npm run test"
+cwd = "$WORKSPACE"
+
+[hostdo.command_aliases.bun_test]
+cmd = "bun test"
+cwd = "$WORKSPACE"
+
+[hostdo.command_aliases.dev]
+cmd = "npm run dev"
+cwd = "$WORKSPACE"
+
+[network]
+allowlist = [
+    "domain=raw.githubusercontent.com",
+    "domain=github.com",
+    "domain=chatgpt.com",
+    "domain=ab.chatgpt.com",
+    "domain=registry.npmjs.org",
+]

package/jsr.json

@@ -1,6 +1,6 @@
 {
   "name": "@onlycliches/room-kit",
-  "version": "1.0.2",
+  "version": "1.0.5",
   "description": "Type-safe channel primitives for Socket.IO events, requests, streams, and room membership.",
   "exports": "./src/index.ts",
   "publish": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "room-kit",
-  "version": "1.0.2",
+  "version": "1.0.6",
   "description": "Type-safe room membership, presence, and realtime messaging for Socket.IO.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/client.ts

@@ -17,7 +17,7 @@ import type {
     RoomListenApi,
     RoomRpc,
     RpcClientApi,
-} from "./types";
+} from "./types.js";
 
 const JOIN_EVENT = "room-kit:join";
 const LEAVE_EVENT = "room-kit:leave";

package/src/index.ts

@@ -1,7 +1,7 @@
-export { ClientSafeError } from "./types";
-export { createRoomClient } from "./client";
-export { defineRoomType } from "./room";
-export { serveRoomType } from "./server";
+export { ClientSafeError } from "./types.js";
+export { createRoomClient } from "./client.js";
+export { defineRoomType } from "./room.js";
+export { serveRoomType } from "./server.js";
 
 export type {
     ClientConnectionState,
@@ -29,6 +29,7 @@ export type {
     RoomServerHandlers,
     RoomSnapshot,
     ServerAdmission,
+    ServerAdmissionInput,
     ServerSocketLike,
     VisibleMemberFor,
-} from "./types";
+} from "./types.js";

package/src/room.ts

@@ -1,4 +1,4 @@
-import type { RoomDefinition, RoomSchema } from "./types";
+import type { RoomDefinition, RoomSchema } from "./types.js";
 
 /**
  * Defines a room type using a type-only schema and runtime options.

package/src/server.ts

@@ -3,6 +3,7 @@ import type {
     EventEmitApi,
     EventMetaFor,
     JoinRequest,
+    MemberProfileFor,
     PresenceFor,
     PresenceListQuery,
     PresencePageFor,
@@ -10,6 +11,7 @@ import type {
     RoomMemberSnapshot,
     RoomDefinition,
     RoomEvents,
+    RoomProfileFor,
     RoomServerAdapter,
     RoomServerBroadcastApi,
     RoomServerHandle,
@@ -18,10 +20,11 @@ import type {
     RoomSnapshot,
     ServerSocketLike,
     ServerStateFor,
+    ServerAdmission,
     PresenceValueFor,
     VisibleMemberFor,
-} from "./types";
-import { ClientSafeError } from "./types";
+} from "./types.js";
+import { ClientSafeError } from "./types.js";
 
 const JOIN_EVENT = "room-kit:join";
 const LEAVE_EVENT = "room-kit:leave";
@@ -178,6 +181,7 @@ type NamespaceState = {
 type AuthCacheEntry<TAuth> = {
     pending?: Promise<TAuth>;
     value?: TAuth;
+    hasValue?: boolean;
 };
 
 const namespaceStates = new WeakMap<object, NamespaceState>();
@@ -247,11 +251,12 @@ export function serveRoomType<TRoom extends RoomDefinition<any>, TAuth = unknown
                 roomProfile: undefined,
                 serverState: initialState,
             });
-            const admission = await handlers.admit(frame.payload as JoinRequest<TRoom>, provisional);
-            assertMatchingRoomIds(
+            const admission = await resolveAdmission(
+                socket,
+                handlers,
                 requestedRoomId,
-                admission.roomId,
-                (admission.roomProfile as { roomId: string }).roomId,
+                frame.payload as JoinRequest<TRoom>,
+                provisional,
             );
 
             const roomState: RoomState<TRoom> = roomCollection.get(admission.roomId) ?? {
@@ -650,7 +655,7 @@ async function resolveSocketAuth<TAuth>(
         return entry.pending;
     }
 
-    if (entry.value === undefined) {
+    if (!entry.hasValue) {
         const pending = Promise.resolve(handlers.onAuth?.(socket) as TAuth)
             .then((auth) => {
                 if (auth === false) {
@@ -660,6 +665,7 @@ async function resolveSocketAuth<TAuth>(
 
                 const current = authCache.get(socket) ?? {};
                 current.value = auth;
+                current.hasValue = true;
                 current.pending = undefined;
                 authCache.set(socket, current);
                 return auth;
@@ -692,6 +698,26 @@ async function resolveSocketAuth<TAuth>(
     handleRejectedAuth(authCache, socket, decision);
 }
 
+async function resolveAdmission<TRoom extends RoomDefinition<any>, TAuth>(
+    socket: ServerSocketLike,
+    handlers: RoomServerHandlers<TRoom, TAuth>,
+    joinRoomId: string,
+    join: JoinRequest<TRoom>,
+    ctx: RoomServerContext<TRoom, TAuth>,
+): Promise<ServerAdmission<TRoom>> {
+    const admission = handlers.admit ? await Promise.resolve(handlers.admit(join, ctx)) : {};
+    const roomId = admission.roomId ?? joinRoomId;
+    const roomProfile = admission.roomProfile ?? ({ roomId } as RoomProfileFor<TRoom>);
+    assertMatchingRoomIds(joinRoomId, roomId, (roomProfile as { roomId: string }).roomId);
+
+    return {
+        roomId,
+        memberId: admission.memberId ?? socket.id,
+        memberProfile: admission.memberProfile ?? ({} as MemberProfileFor<TRoom>),
+        roomProfile,
+    };
+}
+
 function handleRejectedAuth<TAuth>(
     authCache: WeakMap<ServerSocketLike, AuthCacheEntry<TAuth>>,
     socket: ServerSocketLike,

package/src/types.ts

@@ -381,7 +381,12 @@ export type EventListenApi<TRoom extends RoomDefinition<any>> = {
 };
 
 /**
- * Successful admission payload returned by `handlers.admit`.
+ * Successful admission payload used by the runtime after admission is
+ * normalized.
+ *
+ * The server persists these values as the membership record for the socket.
+ * `roomId`, `memberId`, `memberProfile`, and `roomProfile` must all be
+ * present in the finalized admission record.
  */
 export type ServerAdmission<TRoom extends RoomDefinition<any>> = {
     roomId: string;
@@ -390,6 +395,24 @@ export type ServerAdmission<TRoom extends RoomDefinition<any>> = {
     roomProfile: RoomProfileFor<TRoom>;
 };
 
+/**
+ * Partial admission payload accepted from `handlers.admit`.
+ *
+ * Handlers may return only the fields they want to override. The runtime fills
+ * missing values with:
+ *
+ * - `roomId`: the join request room id
+ * - `memberId`: the connected socket id
+ * - `memberProfile`: an empty object
+ * - `roomProfile`: an object with the resolved `roomId`
+ *
+ * The runtime still validates that any supplied `roomId` matches the join
+ * request and that any supplied `roomProfile.roomId` matches the resolved room
+ * id.
+ *
+ */
+export type ServerAdmissionInput<TRoom extends RoomDefinition<any>> = Partial<ServerAdmission<TRoom>>;
+
 /**
  * Optional decision result returned by `revalidateAuth`.
  *
@@ -407,10 +430,6 @@ export type AuthRevalidationDecision<TAuth> =
         message?: string;
     };
 
-type IsUnknown<T> = unknown extends T
-    ? ([T] extends [unknown] ? true : false)
-    : false;
-
 type RoomServerHandlersCommon<TRoom extends RoomDefinition<any>, TAuth> = {
     initState?(join: JoinRequest<TRoom>): Promise<ServerStateFor<TRoom>> | ServerStateFor<TRoom>;
     /**
@@ -428,7 +447,13 @@ type RoomServerHandlersCommon<TRoom extends RoomDefinition<any>, TAuth> = {
      * `{ kind: "reject", message }` to reject the operation.
      */
     revalidateAuth?(socket: ServerSocketLike, auth: TAuth): Promise<AuthRevalidationDecision<TAuth> | void> | AuthRevalidationDecision<TAuth> | void;
-    admit(join: JoinRequest<TRoom>, ctx: RoomServerContext<TRoom, TAuth>): Promise<ServerAdmission<TRoom>> | ServerAdmission<TRoom>;
+    /**
+     * Optional join admission hook.
+     *
+     * Return only the pieces you want to override. Missing fields are filled
+     * by the runtime.
+     */
+    admit?(join: JoinRequest<TRoom>, ctx: RoomServerContext<TRoom, TAuth>): Promise<ServerAdmissionInput<TRoom>> | ServerAdmissionInput<TRoom>;
     /**
      * Called once when a server socket disconnects.
      *
@@ -459,19 +484,21 @@ type RoomServerHandlersCommon<TRoom extends RoomDefinition<any>, TAuth> = {
 /**
  * Server handler contract for a room type.
  *
- * `onAuth` is required when `TAuth` is explicitly typed to a non-`unknown`
- * shape, and optional otherwise.
+ * `onAuth` and `admit` are both optional.
  *
- * Returning `false` rejects the socket before any room state is initialized.
+ * When `onAuth` is omitted, the socket is accepted with an `undefined` auth
+ * value. Returning `false` from `onAuth` still rejects the socket before room
+ * initialization.
+ *
+ * When `admit` is omitted, the runtime derives the admission record from the
+ * join request and socket id. When `admit` is present, it may return a partial
+ * admission and the server will fill in any missing fields as described by
+ * `ServerAdmissionInput`.
  */
 export type RoomServerHandlers<TRoom extends RoomDefinition<any>, TAuth = unknown> =
-    IsUnknown<TAuth> extends true
-        ? RoomServerHandlersCommon<TRoom, TAuth> & {
-            onAuth?(socket: ServerSocketLike): Promise<TAuth | false> | TAuth | false;
-        }
-        : RoomServerHandlersCommon<TRoom, TAuth> & {
-            onAuth(socket: ServerSocketLike): Promise<TAuth | false> | TAuth | false;
-        };
+    RoomServerHandlersCommon<TRoom, TAuth> & {
+        onAuth?(socket: ServerSocketLike): Promise<TAuth | false> | TAuth | false;
+    };
 
 /**
  * Context provided to server handlers (`admit`, `rpc`, `events`, join/leave).

package/test/room.spec.ts

@@ -875,6 +875,77 @@ describe("room kit", () => {
 		connection.close();
 	});
 
+	it("uses default auth and admission when handlers are omitted", async () => {
+		const namespace = new MockNamespace();
+		const roomType = createRoomType("default-server-config", "list");
+		const { client, connection, stop } = createClientPair(namespace, "alice-socket", roomType, {});
+
+		const joined = await client.join({
+			roomId: "room-1",
+			roomKey: "shared-key",
+			userId: "alice",
+			userName: "Ada",
+		});
+
+		expect(joined.memberId).toBe("alice-socket");
+		expect(joined.roomProfile).toMatchObject({
+			roomId: "room-1",
+		});
+		expect(stop.room("room-1")).toMatchObject({
+			roomId: "room-1",
+			members: [
+				{
+					memberId: "alice-socket",
+					memberProfile: {},
+				},
+			],
+		});
+
+		stop.cleanup();
+		connection.close();
+	});
+
+	it("fills in omitted admission fields", async () => {
+		const namespace = new MockNamespace();
+		const roomType = createRoomType("partial-admission", "list");
+		const handlers: RoomServerHandlers<typeof roomType> = {
+			admit: (join) => ({
+				memberProfile: {
+					userId: join.userId,
+					userName: join.userName,
+				},
+			}),
+		};
+		const { client, connection, stop } = createClientPair(namespace, "alice-socket", roomType, handlers);
+
+		const joined = await client.join({
+			roomId: "room-1",
+			roomKey: "shared-key",
+			userId: "alice",
+			userName: "Ada",
+		});
+
+		expect(joined.memberId).toBe("alice-socket");
+		expect(joined.roomProfile).toMatchObject({
+			roomId: "room-1",
+		});
+		expect(stop.room("room-1")).toMatchObject({
+			roomId: "room-1",
+			members: [
+				{
+					memberId: "alice-socket",
+					memberProfile: {
+						userId: "alice",
+						userName: "Ada",
+					},
+				},
+			],
+		});
+
+		stop.cleanup();
+		connection.close();
+	});
+
 	it("rejects when onAuth fails", async () => {
 		const namespace = new MockNamespace();
 		const roomType = createRoomType("reject-auth", "list");

package/tsconfig.json

@@ -1,8 +1,8 @@
 {
   "compilerOptions": {
     "target": "esnext",
-    "module": "esnext",
-    "moduleResolution": "node",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
     "lib": ["ESNext"],
     "rootDir": "./src",
     "outDir": "./dist",