@johnhenry/wsh 0.19.1 → 0.21.0

package/src/server/json-schema.mjs

@@ -0,0 +1,204 @@
+/**
+ * A small JSON Schema validator for `@johnhenry/wsh/server`'s MCP tools.
+ *
+ * MCP arguments come off the wire from an authenticated-but-untrusted client,
+ * so the tool's `inputSchema` is enforced before `call()` runs. The package has
+ * no runtime dependencies, so this covers the keywords tool schemas actually
+ * use rather than all of JSON Schema: `type`, `enum`, `const`, `properties`,
+ * `required`, `additionalProperties`, `items`, `min/maxItems`, `uniqueItems`,
+ * `min/maxLength`, `pattern`, `minimum`/`maximum` (and exclusive forms),
+ * `multipleOf`, `allOf`/`anyOf`/`oneOf`/`not`, and local `$ref` (`#/...`).
+ * `format`, `title`, `description`, `default` and other annotations are ignored.
+ *
+ * A schema that uses a keyword this does not understand is refused up front
+ * (`assertSupportedSchema`) rather than silently validating less than the
+ * operator wrote.
+ */
+
+const TYPES = new Set(['string', 'number', 'integer', 'boolean', 'null', 'object', 'array']);
+const IGNORED = new Set([
+  '$schema', '$id', '$comment', 'title', 'description', 'default', 'examples', 'format',
+  'definitions', '$defs', 'deprecated', 'readOnly', 'writeOnly',
+]);
+const KNOWN = new Set([
+  'type', 'enum', 'const', 'properties', 'required', 'additionalProperties', 'items',
+  'minItems', 'maxItems', 'uniqueItems', 'minLength', 'maxLength', 'pattern', 'minimum',
+  'maximum', 'exclusiveMinimum', 'exclusiveMaximum', 'multipleOf', 'allOf', 'anyOf',
+  'oneOf', 'not', '$ref', 'minProperties', 'maxProperties',
+]);
+const MAX_DEPTH = 64;
+
+const isObject = (v) => v !== null && typeof v === 'object' && !Array.isArray(v);
+
+function typeOf(v) {
+  if (v === null) return 'null';
+  if (Array.isArray(v)) return 'array';
+  if (typeof v === 'number') return Number.isInteger(v) ? 'integer' : 'number';
+  return typeof v;
+}
+
+function matchesType(v, t) {
+  const actual = typeOf(v);
+  return actual === t || (t === 'number' && actual === 'integer');
+}
+
+/** Structural JSON equality (for `enum` / `const` / `uniqueItems`). */
+function deepEqual(a, b) {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== 'object') return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  if (Array.isArray(a)) return a.length === b.length && a.every((x, i) => deepEqual(x, b[i]));
+  const ka = Object.keys(a);
+  const kb = Object.keys(b);
+  return ka.length === kb.length && ka.every((k) => Object.hasOwn(b, k) && deepEqual(a[k], b[k]));
+}
+
+/**
+ * Throw if `schema` uses a keyword this validator does not implement, or is
+ * otherwise malformed. Run once when the operator's tools are configured.
+ */
+export function assertSupportedSchema(schema, path = '#', depth = 0) {
+  if (depth > MAX_DEPTH) throw new TypeError(`inputSchema at ${path} is nested too deeply`);
+  if (schema === true || schema === false) return;
+  if (!isObject(schema)) throw new TypeError(`inputSchema at ${path} must be an object`);
+  for (const key of Object.keys(schema)) {
+    if (!KNOWN.has(key) && !IGNORED.has(key)) {
+      throw new TypeError(`inputSchema at ${path} uses unsupported keyword "${key}"`);
+    }
+  }
+  if (schema.type !== undefined) {
+    const types = Array.isArray(schema.type) ? schema.type : [schema.type];
+    for (const t of types) if (!TYPES.has(t)) throw new TypeError(`inputSchema at ${path} has unknown type ${JSON.stringify(t)}`);
+  }
+  if (schema.pattern !== undefined) {
+    try { new RegExp(schema.pattern, 'u'); } catch { throw new TypeError(`inputSchema at ${path} has an invalid pattern`); }
+  }
+  if (schema.required !== undefined && !(Array.isArray(schema.required) && schema.required.every((r) => typeof r === 'string'))) {
+    throw new TypeError(`inputSchema at ${path}: required must be an array of strings`);
+  }
+  if (isObject(schema.properties)) {
+    for (const [k, s] of Object.entries(schema.properties)) assertSupportedSchema(s, `${path}/properties/${k}`, depth + 1);
+  } else if (schema.properties !== undefined) {
+    throw new TypeError(`inputSchema at ${path}: properties must be an object`);
+  }
+  if (schema.additionalProperties !== undefined && typeof schema.additionalProperties !== 'boolean') {
+    assertSupportedSchema(schema.additionalProperties, `${path}/additionalProperties`, depth + 1);
+  }
+  if (schema.items !== undefined) assertSupportedSchema(schema.items, `${path}/items`, depth + 1);
+  for (const k of ['allOf', 'anyOf', 'oneOf']) {
+    if (schema[k] === undefined) continue;
+    if (!Array.isArray(schema[k])) throw new TypeError(`inputSchema at ${path}: ${k} must be an array`);
+    schema[k].forEach((s, i) => assertSupportedSchema(s, `${path}/${k}/${i}`, depth + 1));
+  }
+  if (schema.not !== undefined) assertSupportedSchema(schema.not, `${path}/not`, depth + 1);
+  for (const k of ['definitions', '$defs']) {
+    if (isObject(schema[k])) for (const [n, s] of Object.entries(schema[k])) assertSupportedSchema(s, `${path}/${k}/${n}`, depth + 1);
+  }
+  if (schema.$ref !== undefined && !(typeof schema.$ref === 'string' && schema.$ref.startsWith('#'))) {
+    throw new TypeError(`inputSchema at ${path}: only local "#..." $ref is supported`);
+  }
+}
+
+function resolveRef(root, ref) {
+  if (ref === '#') return root;
+  if (!ref.startsWith('#/')) return undefined;
+  let node = root;
+  for (const raw of ref.slice(2).split('/')) {
+    const seg = raw.replace(/~1/g, '/').replace(/~0/g, '~');
+    if (!isObject(node) && !Array.isArray(node)) return undefined;
+    if (!Object.hasOwn(node, seg)) return undefined;
+    node = node[seg];
+  }
+  return node;
+}
+
+/**
+ * Validate `value` against `schema`.
+ * @returns {string | null} `null` when valid, otherwise a short reason naming the path.
+ */
+export function validateSchema(schema, value) {
+  const fail = (path, msg) => `${path || '/'}: ${msg}`;
+
+  function check(s, v, path, depth) {
+    if (depth > MAX_DEPTH) return fail(path, 'schema or value nested too deeply');
+    if (s === true) return null;
+    if (s === false) return fail(path, 'no value is allowed here');
+    if (s.$ref !== undefined) {
+      const target = resolveRef(schema, s.$ref);
+      if (target === undefined) return fail(path, `unresolvable $ref ${s.$ref}`);
+      const r = check(target, v, path, depth + 1);
+      if (r) return r;
+    }
+    if (s.type !== undefined) {
+      const types = Array.isArray(s.type) ? s.type : [s.type];
+      if (!types.some((t) => matchesType(v, t))) return fail(path, `expected ${types.join(' | ')}, got ${typeOf(v)}`);
+    }
+    if (s.enum !== undefined && !s.enum.some((e) => deepEqual(e, v))) return fail(path, 'not one of the allowed values');
+    if (s.const !== undefined && !deepEqual(s.const, v)) return fail(path, 'does not equal the required constant');
+
+    if (typeof v === 'string') {
+      const len = [...v].length;
+      if (s.minLength !== undefined && len < s.minLength) return fail(path, `shorter than ${s.minLength}`);
+      if (s.maxLength !== undefined && len > s.maxLength) return fail(path, `longer than ${s.maxLength}`);
+      if (s.pattern !== undefined && !new RegExp(s.pattern, 'u').test(v)) return fail(path, 'does not match the required pattern');
+    }
+    if (typeof v === 'number') {
+      if (!Number.isFinite(v)) return fail(path, 'must be a finite number');
+      if (s.minimum !== undefined && v < s.minimum) return fail(path, `below the minimum ${s.minimum}`);
+      if (s.maximum !== undefined && v > s.maximum) return fail(path, `above the maximum ${s.maximum}`);
+      if (typeof s.exclusiveMinimum === 'number' && v <= s.exclusiveMinimum) return fail(path, `must be above ${s.exclusiveMinimum}`);
+      if (typeof s.exclusiveMaximum === 'number' && v >= s.exclusiveMaximum) return fail(path, `must be below ${s.exclusiveMaximum}`);
+      if (s.multipleOf !== undefined) {
+        const q = v / s.multipleOf;
+        if (Math.abs(q - Math.round(q)) > 1e-9) return fail(path, `not a multiple of ${s.multipleOf}`);
+      }
+    }
+    if (Array.isArray(v)) {
+      if (s.minItems !== undefined && v.length < s.minItems) return fail(path, `fewer than ${s.minItems} items`);
+      if (s.maxItems !== undefined && v.length > s.maxItems) return fail(path, `more than ${s.maxItems} items`);
+      if (s.uniqueItems === true) {
+        for (let i = 0; i < v.length; i++) {
+          for (let j = i + 1; j < v.length; j++) if (deepEqual(v[i], v[j])) return fail(path, 'items are not unique');
+        }
+      }
+      if (s.items !== undefined) {
+        for (let i = 0; i < v.length; i++) {
+          const r = check(s.items, v[i], `${path}/${i}`, depth + 1);
+          if (r) return r;
+        }
+      }
+    }
+    if (isObject(v)) {
+      const keys = Object.keys(v);
+      if (s.minProperties !== undefined && keys.length < s.minProperties) return fail(path, `fewer than ${s.minProperties} properties`);
+      if (s.maxProperties !== undefined && keys.length > s.maxProperties) return fail(path, `more than ${s.maxProperties} properties`);
+      for (const r of s.required ?? []) if (!Object.hasOwn(v, r)) return fail(path, `missing required property "${r}"`);
+      const props = isObject(s.properties) ? s.properties : {};
+      for (const k of keys) {
+        if (Object.hasOwn(props, k)) {
+          const r = check(props[k], v[k], `${path}/${k}`, depth + 1);
+          if (r) return r;
+        } else if (s.additionalProperties === false) {
+          return fail(path, `unexpected property "${k}"`);
+        } else if (s.additionalProperties !== undefined && s.additionalProperties !== true) {
+          const r = check(s.additionalProperties, v[k], `${path}/${k}`, depth + 1);
+          if (r) return r;
+        }
+      }
+    }
+
+    for (const sub of s.allOf ?? []) {
+      const r = check(sub, v, path, depth + 1);
+      if (r) return r;
+    }
+    if (s.anyOf && !s.anyOf.some((sub) => check(sub, v, path, depth + 1) === null)) return fail(path, 'matches none of the anyOf alternatives');
+    if (s.oneOf) {
+      const n = s.oneOf.filter((sub) => check(sub, v, path, depth + 1) === null).length;
+      if (n !== 1) return fail(path, `matches ${n} of the oneOf alternatives, expected exactly 1`);
+    }
+    if (s.not !== undefined && check(s.not, v, path, depth + 1) === null) return fail(path, 'matches a schema it must not match');
+    return null;
+  }
+
+  return check(schema, value, '', 0);
+}

package/src/server/mcp.mjs

@@ -0,0 +1,111 @@
+/**
+ * MCP tools for `@johnhenry/wsh/server`: what `createWshServer({ mcp })`
+ * exposes through `McpDiscover` / `McpCall`.
+ *
+ * Two sources, which may be combined:
+ *  - `mcp.tools` -- an array of `{ name, description, inputSchema, call }`, or
+ *    a `{ name: { description, inputSchema, call } }` map.
+ *  - `mcp.client` -- anything shaped like an `@modelcontextprotocol/sdk`
+ *    `Client` (`listTools()` / `callTool({ name, arguments })`); its tools are
+ *    proxied. Duck-typed, so the SDK is never imported by this package.
+ *
+ * Tools the operator did not list are never reachable: a call is looked up by
+ * exact name in the set built here, after the optional `authorize` filter.
+ */
+
+import { assertSupportedSchema, validateSchema } from './json-schema.mjs';
+
+const DEFAULT_SCHEMA = Object.freeze({ type: 'object' });
+export const MCP_DEFAULTS = Object.freeze({ maxConcurrent: 8, timeoutMs: 30_000 });
+
+function normalizeTool(name, spec, origin) {
+  if (typeof name !== 'string' || !name) throw new TypeError('createWshServer: every mcp tool needs a name');
+  if (!spec || typeof spec.call !== 'function') {
+    throw new TypeError(`createWshServer: mcp tool "${name}" needs a call(args, ctx) function`);
+  }
+  const inputSchema = spec.inputSchema ?? spec.parameters ?? DEFAULT_SCHEMA;
+  assertSupportedSchema(inputSchema, `#(${name})`);
+  return { name, description: String(spec.description ?? ''), inputSchema, call: spec.call, origin };
+}
+
+/**
+ * @param {object} mcp - the `createWshServer` `mcp` option
+ * @returns {{ list(user: string, who: object): Promise<object[]>, find(name: string, user: string, who: object): Promise<object | null>, maxConcurrent: number, timeoutMs: number }}
+ */
+export function createMcpHost(mcp) {
+  if (!mcp || typeof mcp !== 'object') throw new TypeError('createWshServer: mcp must be an object');
+  const local = new Map();
+  const entries = Array.isArray(mcp.tools)
+    ? mcp.tools.map((t) => [t?.name, t])
+    : Object.entries(mcp.tools ?? {});
+  for (const [name, spec] of entries) {
+    if (local.has(name)) throw new TypeError(`createWshServer: duplicate mcp tool "${name}"`);
+    local.set(name, normalizeTool(name, spec, 'local'));
+  }
+  const client = mcp.client ?? null;
+  if (client && (typeof client.listTools !== 'function' || typeof client.callTool !== 'function')) {
+    throw new TypeError('createWshServer: mcp.client needs listTools() and callTool() (an @modelcontextprotocol/sdk Client)');
+  }
+  if (typeof mcp.authorize !== 'undefined' && typeof mcp.authorize !== 'function') {
+    throw new TypeError('createWshServer: mcp.authorize must be a function');
+  }
+
+  /** Remote tools, refreshed on every discover; calls use the most recent listing. */
+  let proxied = new Map();
+  async function refreshProxied() {
+    if (!client) return;
+    const next = new Map();
+    const { tools = [] } = await client.listTools();
+    for (const t of tools) {
+      if (!t || typeof t.name !== 'string' || local.has(t.name)) continue; // local tools win
+      try {
+        next.set(t.name, normalizeTool(t.name, {
+          description: t.description,
+          inputSchema: t.inputSchema,
+          call: (args, ctx) => callProxied(t.name, args, ctx),
+        }, 'proxy'));
+      } catch { /* a schema we cannot enforce is not exposed */ }
+    }
+    proxied = next;
+  }
+
+  async function callProxied(name, args, { signal }) {
+    const res = await client.callTool({ name, arguments: args }, undefined, { signal });
+    if (res?.isError) {
+      const text = Array.isArray(res.content) ? res.content.filter((c) => c?.type === 'text').map((c) => c.text).join('\n') : '';
+      throw new Error(text || `tool ${name} failed`);
+    }
+    return res?.structuredContent ?? res?.content ?? null;
+  }
+
+  const allowed = async (tool, user, who) => {
+    if (!mcp.authorize) return true;
+    try { return (await mcp.authorize(user, { name: tool.name, description: tool.description, inputSchema: tool.inputSchema }, who)) === true; } catch { return false; }
+  };
+
+  return {
+    maxConcurrent: mcp.maxConcurrent > 0 ? mcp.maxConcurrent : MCP_DEFAULTS.maxConcurrent,
+    timeoutMs: mcp.timeoutMs >= 0 ? mcp.timeoutMs : MCP_DEFAULTS.timeoutMs,
+
+    async list(user, who) {
+      await refreshProxied();
+      const out = [];
+      for (const t of [...local.values(), ...proxied.values()]) {
+        if (await allowed(t, user, who)) out.push({ name: t.name, description: t.description, parameters: t.inputSchema });
+      }
+      return out;
+    },
+
+    /** A tool this principal may call, or `null` -- indistinguishable for hidden and absent. */
+    async find(name, user, who) {
+      let tool = local.get(name) ?? proxied.get(name);
+      if (!tool && client && !local.has(name)) {
+        await refreshProxied();
+        tool = proxied.get(name);
+      }
+      return tool && await allowed(tool, user, who) ? tool : null;
+    },
+
+    validate: (tool, args) => validateSchema(tool.inputSchema, args),
+  };
+}

package/src/server/sessions.mjs

@@ -0,0 +1,263 @@
+/**
+ * Session registry for `@johnhenry/wsh/server`: what lets an exec/pty session
+ * outlive the connection that opened it (`createWshServer({ sessions })`).
+ *
+ * The registry is per server and holds a `HostedSession` for every pty/exec
+ * session. A connection's channel is an *attachment* to one: output is
+ * appended to the session's ring buffer and fanned out to every attachment,
+ * so when a socket drops the process keeps running and its newest output keeps
+ * accumulating until `detachTtlMs` elapses or a client resumes.
+ *
+ * `seq` -- the one design question the wire does not answer -- is defined as
+ * the cumulative count of output BYTES the host has produced for a session.
+ * A client counts what it has received (it sees every byte), passes that as
+ * `Resume.last_seq`, and the host replays `ring[last_seq - ringStart ..]`.
+ * See spec/wsh-v1.yaml (`Resume`, `AttachmentInfo`).
+ */
+
+import { createHmac, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+
+export const DEFAULT_RING_BYTES = 1024 * 1024;
+export const DEFAULT_DETACH_TTL_MS = 300_000;
+export const DEFAULT_MAX_DETACHED = 16;
+export const MAX_ATTACHMENTS = 16;
+
+const NO_EXPIRY = Buffer.alloc(8, 0xff);
+
+/**
+ * A bounded byte history addressed by absolute stream position.
+ * `start` is the seq of the oldest retained byte, `end` the seq one past the newest.
+ */
+export class ByteRing {
+  #chunks = [];
+  #size = 0;
+  start = 0;
+  end = 0;
+
+  constructor(maxBytes) {
+    this.max = maxBytes;
+  }
+
+  push(bytes) {
+    if (!bytes.byteLength) return;
+    this.#chunks.push(Uint8Array.from(bytes));
+    this.#size += bytes.byteLength;
+    this.end += bytes.byteLength;
+    while (this.#size > this.max) {
+      const excess = this.#size - this.max;
+      const first = this.#chunks[0];
+      if (first.byteLength <= excess) {
+        this.#chunks.shift();
+        this.#size -= first.byteLength;
+        this.start += first.byteLength;
+      } else {
+        this.#chunks[0] = first.subarray(excess);
+        this.#size -= excess;
+        this.start += excess;
+      }
+    }
+  }
+
+  /** Bytes from absolute position `from` (clamped to `start`) to the end. */
+  read(from = this.start) {
+    const skip = Math.max(0, from - this.start);
+    const out = new Uint8Array(Math.max(0, this.#size - skip));
+    let at = 0;
+    let seen = 0;
+    for (const c of this.#chunks) {
+      if (seen + c.byteLength > skip) {
+        const part = c.subarray(Math.max(0, skip - seen));
+        out.set(part, at);
+        at += part.byteLength;
+      }
+      seen += c.byteLength;
+    }
+    return out;
+  }
+}
+
+/**
+ * Mint a session token in the spec's format: `[8B expiry][32B HMAC-SHA256(secret, session_id || expiry)]`.
+ * A session's lifetime is governed by `detachTtlMs`, not by its token, so the expiry is the maximum.
+ */
+export function mintToken(secret, sessionId) {
+  const mac = createHmac('sha256', secret).update(sessionId).update(NO_EXPIRY).digest();
+  return new Uint8Array(Buffer.concat([NO_EXPIRY, mac]));
+}
+
+/** Constant-time verification of a token minted by `mintToken` for exactly this session id. */
+export function verifyToken(secret, sessionId, token) {
+  if (!(token instanceof Uint8Array) || token.byteLength !== 40) return false;
+  const buf = Buffer.from(token.buffer, token.byteOffset, token.byteLength);
+  const expiry = buf.subarray(0, 8);
+  if (expiry.readBigUInt64BE() < BigInt(Math.floor(Date.now() / 1000))) return false;
+  const want = createHmac('sha256', secret).update(sessionId).update(expiry).digest();
+  return timingSafeEqual(want, buf.subarray(8));
+}
+
+/**
+ * One attached connection's view of a session; `connection.mjs` builds them.
+ * @typedef {object} Attachment
+ * @property {number} connId
+ * @property {number} channelId
+ * @property {'control' | 'readonly'} mode
+ * @property {string} username
+ * @property {string} principal - who this connection authenticated as (see `principalKey`)
+ * @property {(bytes: Uint8Array) => unknown} write - live output
+ * @property {(msg: object) => unknown} notify - an ordered control message (e.g. Presence)
+ * @property {(code: number) => unknown} exit - the session ended
+ */
+
+export class HostedSession {
+  /** @type {Set<Attachment>} */
+  attachments = new Set();
+  state = 'attached';
+  exitCode = null;
+  createdAt = Date.now();
+  lastActivity = Date.now();
+  detachedAt = 0;
+  name;
+  #timer = null;
+
+  constructor(registry, { id, token, owner, kind, command, ringBytes }) {
+    this.registry = registry;
+    this.id = id;
+    this.token = token;
+    this.owner = owner;
+    this.kind = kind;
+    this.command = command;
+    this.ring = new ByteRing(ringBytes);
+    /** Set by the connection once the process exists: `{ input, inputEnd, resize, signal, kill }`. */
+    this.handlers = {};
+  }
+
+  /** Output from the process: retained in the ring, delivered to every attachment. */
+  push(bytes) {
+    this.lastActivity = Date.now();
+    this.ring.push(bytes);
+    for (const a of this.attachments) a.write(bytes);
+  }
+
+  attach(att) {
+    this.attachments.add(att);
+    this.state = 'attached';
+    this.#clearTimer();
+    this.broadcastPresence(att);
+  }
+
+  detach(att) {
+    if (!this.attachments.delete(att)) return;
+    this.broadcastPresence();
+    if (this.attachments.size === 0) this.#markDetached();
+  }
+
+  roster() {
+    return [...this.attachments].map((a) => ({ session_id: this.id, mode: a.mode, username: a.username }));
+  }
+
+  /** Tell every attachment (except `except`) who is attached now. */
+  broadcastPresence(except) {
+    if (this.attachments.size === 0) return;
+    const msg = { attachments: this.roster() };
+    for (const a of this.attachments) if (a !== except) a.notify(msg);
+  }
+
+  /** The process ended. Everyone attached hears Exit + Close; the record lingers for late resumes. */
+  finish(code) {
+    if (this.state === 'exited') return;
+    this.exitCode = code;
+    this.state = 'exited';
+    const att = [...this.attachments];
+    this.attachments.clear();
+    for (const a of att) a.exit(code);
+    this.#markDetached();
+  }
+
+  kill() {
+    try { this.handlers.kill?.(); } catch { /* already gone */ }
+  }
+
+  /** Forget the session (and stop it if it is still running). */
+  dispose() {
+    this.#clearTimer();
+    this.registry._forget(this);
+    if (this.state !== 'exited') {
+      this.kill();
+      this.state = 'exited';
+    }
+  }
+
+  #markDetached() {
+    this.detachedAt = Date.now();
+    if (this.state !== 'exited') this.state = 'detached';
+    this.#clearTimer();
+    const ttl = this.registry.detachTtlMs;
+    if (ttl <= 0) { this.dispose(); return; }
+    this.#timer = setTimeout(() => {
+      this.registry.log(`session ${this.id} expired after ${ttl}ms detached`);
+      this.dispose();
+    }, ttl);
+    this.#timer.unref?.();
+    this.registry._enforceMaxDetached(this);
+  }
+
+  #clearTimer() {
+    clearTimeout(this.#timer);
+    this.#timer = null;
+  }
+}
+
+export class SessionRegistry {
+  /** @type {Map<string, HostedSession>} */
+  #sessions = new Map();
+
+  constructor({ secret, detachTtlMs = DEFAULT_DETACH_TTL_MS, maxDetached = DEFAULT_MAX_DETACHED, ringBytes = DEFAULT_RING_BYTES, log = () => {} } = {}) {
+    this.secret = secret ?? randomBytes(32);
+    this.detachTtlMs = detachTtlMs;
+    this.maxDetached = maxDetached;
+    this.ringBytes = ringBytes;
+    this.log = log;
+  }
+
+  /** @param {{ owner: { username: string, principal: string, fingerprint: string | null }, kind: 'pty' | 'exec', command?: string }} spec */
+  create({ owner, kind, command }) {
+    const id = randomUUID();
+    const s = new HostedSession(this, { id, token: mintToken(this.secret, id), owner, kind, command, ringBytes: this.ringBytes });
+    this.#sessions.set(id, s);
+    return s;
+  }
+
+  get(id) {
+    return typeof id === 'string' ? this.#sessions.get(id) : undefined;
+  }
+
+  checkToken(session, token) {
+    return verifyToken(this.secret, session.id, token);
+  }
+
+  /** Sessions this principal owns. */
+  listFor(principal) {
+    return [...this.#sessions.values()].filter((s) => s.owner.principal === principal);
+  }
+
+  get size() { return this.#sessions.size; }
+
+  /** Kill everything (server shutdown). */
+  closeAll() {
+    for (const s of [...this.#sessions.values()]) s.dispose();
+  }
+
+  _forget(session) {
+    this.#sessions.delete(session.id);
+  }
+
+  /** Keep at most `maxDetached` unattended sessions: the longest-detached are killed first. */
+  _enforceMaxDetached() {
+    const detached = [...this.#sessions.values()].filter((s) => s.attachments.size === 0).sort((a, b) => a.detachedAt - b.detachedAt);
+    while (detached.length > this.maxDetached) {
+      const victim = detached.shift();
+      this.log(`session ${victim.id} evicted (more than ${this.maxDetached} detached)`);
+      victim.dispose();
+    }
+  }
+}

package/src/session.mjs

@@ -76,6 +76,12 @@ export class WshSession {
    */
   #resumeToken;
 
+  /**
+   * Cumulative session OUTPUT BYTES received so far (see `seq`).
+   * @type {number}
+   */
+  #seq = 0;
+
   /**
    * Stream IDs returned by the server in OPEN_OK.
    * Typically { stdin: number, stdout: number } or a single bidirectional ID.
@@ -270,6 +276,27 @@ export class WshSession {
     return this.#resumeToken;
   }
 
+  /**
+   * How many bytes of this session's output this client has received: the
+   * host's `seq` for the next byte. Pass it as `lastSeq` to
+   * `WshClient.resumeSession()` so a resume replays only what was missed. For a
+   * session obtained from `attachSession()`/`resumeSession()` it starts at the
+   * host's position of the first replayed byte, so it is an absolute position
+   * either way. Counts bytes delivered to `onData`.
+   * @returns {number}
+   */
+  get seq() {
+    return this.#seq;
+  }
+
+  /**
+   * Set the starting position of a session obtained by attach/resume.
+   * @internal
+   */
+  _setSeq(n) {
+    this.#seq = n;
+  }
+
   /** Current session state. */
   get state() {
     return this.#state;
@@ -657,6 +684,7 @@ export class WshSession {
         if (msg.data && msg.data.byteLength > 0) {
           this.#virtualBackend?.pushData(msg.data);
           try {
+            this.#seq += msg.data.byteLength;
             this.onData?.(msg.data);
           } catch (err) {
             console.error('[wsh:session] onData handler error:', err);
@@ -688,6 +716,7 @@ export class WshSession {
           .then((plaintext) => {
             this.#virtualBackend?.pushData(plaintext);
             try {
+              this.#seq += plaintext.byteLength;
               this.onData?.(plaintext);
             } catch (err) {
               console.error('[wsh:session] onData handler error:', err);
@@ -898,6 +927,7 @@ export class WshSession {
             }
             for (const plaintext of deliverable) {
               try {
+                this.#seq += plaintext.byteLength;
                 this.onData?.(plaintext);
               } catch (err) {
                 console.error('[wsh:session] onData handler error:', err);
@@ -905,6 +935,7 @@ export class WshSession {
             }
           } else {
             try {
+              this.#seq += value.byteLength;
               this.onData?.(value);
             } catch (err) {
               console.error('[wsh:session] onData handler error:', err);