@intx/hub-sessions 0.1.2 → 0.2.2

package/src/skill-kind.ts

@@ -1,350 +0,0 @@
-import { type } from "arktype";
-import { getLogger } from "@intx/log";
-import { glob, repoActionToGrantVerb } from "@intx/hub-common";
-import {
-  UserPrincipal,
-  type AuthorizeFn,
-  type KindHandler,
-  type Principal,
-  type ValidatePushResult,
-} from "./repo-store";
-
-const logger = getLogger(["hub-sessions", "skill-kind"]);
-
-export type SkillHubPrincipal = { readonly kind: "hub" };
-
-export type SkillSidecarPrincipal = {
-  readonly kind: "sidecar";
-  readonly agentId: string;
-};
-
-export type SkillPrincipal = SkillHubPrincipal | SkillSidecarPrincipal;
-
-/**
- * arktype schema for the SKILL.md frontmatter. Required fields are
- * `name` and `description`; the Claude Code superset of optional fields
- * (`when_to_use`, `allowed-tools`, `paths`, `model`, ...) is accepted
- * via `onUndeclaredKey("ignore")` but not enforced.
- *
- * The forbidden-name narrow rejects `"anthropic"` and `"claude"`
- * because those values are reserved by the upstream agentskills.io
- * spec for vendor-owned skill packs.
- */
-export const skillFrontmatterSchema = type({
-  name: type(/^[a-z0-9]+(-[a-z0-9]+)*$/)
-    .and("string<=64")
-    .narrow((n: string, ctx) => {
-      if (n === "anthropic" || n === "claude") {
-        return ctx.mustBe(`not the reserved name "anthropic" or "claude"`);
-      }
-      return true;
-    }),
-  description: type("1 <= string <= 1024").and(type(/^(?!.*<[^>]+>).*$/s)),
-}).onUndeclaredKey("ignore");
-
-export type SkillFrontmatter = typeof skillFrontmatterSchema.infer;
-
-export type SkillIndexEntry = {
-  /** Equal to the containing directory name and to `frontmatter.name`. */
-  name: string;
-  description: string;
-  /** Full parsed frontmatter, including any accepted optional fields. */
-  frontmatter: Record<string, unknown>;
-  /** Path of the skill subdirectory relative to the asset mount, with trailing slash. */
-  workspaceSubpath: string;
-};
-
-type CacheKey = string;
-
-function cacheKey(assetId: string, ref: string): CacheKey {
-  return `${assetId}\u0000${ref}`;
-}
-
-const skillIndex = new Map<CacheKey, SkillIndexEntry[]>();
-const pendingIndex = new Map<CacheKey, SkillIndexEntry[]>();
-
-/**
- * Returns the parsed skill index for `(assetId, ref)`, or an empty
- * array if no index has been populated yet. The index is refreshed by
- * the kind handler's `onRefUpdated` hook after each successful write.
- */
-export function getSkillIndex(assetId: string, ref: string): SkillIndexEntry[] {
-  return skillIndex.get(cacheKey(assetId, ref)) ?? [];
-}
-
-const FRONTMATTER_DELIMITER = "---";
-
-type ParsedSkillMd = {
-  frontmatter: Record<string, unknown>;
-};
-
-const YamlMapping = type("Record<string, unknown>");
-
-function parseSkillMd(body: string): ParsedSkillMd {
-  const lines = body.split(/\r?\n/);
-  if (lines[0] !== FRONTMATTER_DELIMITER) {
-    throw new Error("SKILL.md is missing YAML frontmatter delimiter");
-  }
-  let endIdx = -1;
-  for (let i = 1; i < lines.length; i += 1) {
-    if (lines[i] === FRONTMATTER_DELIMITER) {
-      endIdx = i;
-      break;
-    }
-  }
-  if (endIdx === -1) {
-    throw new Error("SKILL.md frontmatter has no closing delimiter");
-  }
-  const yamlText = lines.slice(1, endIdx).join("\n");
-  const parsed: unknown = Bun.YAML.parse(yamlText);
-  const validated = YamlMapping(parsed);
-  if (validated instanceof type.errors) {
-    throw new Error(
-      `SKILL.md frontmatter must be a YAML mapping: ${validated.summary}`,
-    );
-  }
-  return { frontmatter: validated };
-}
-
-type ParseOutcome =
-  | { ok: true; entry: SkillIndexEntry }
-  | { ok: false; reason: string };
-
-async function parseSkillEntry(
-  subdir: string,
-  readBlob: (path: string) => Promise<Uint8Array>,
-): Promise<ParseOutcome> {
-  const skillPath = `${subdir}/SKILL.md`;
-  let raw: Uint8Array;
-  try {
-    raw = await readBlob(skillPath);
-  } catch (cause) {
-    return {
-      ok: false,
-      reason: `skill ${subdir} is missing SKILL.md: ${
-        cause instanceof Error ? cause.message : String(cause)
-      }`,
-    };
-  }
-
-  const body = new TextDecoder().decode(raw);
-  let parsed: ParsedSkillMd;
-  try {
-    parsed = parseSkillMd(body);
-  } catch (cause) {
-    return {
-      ok: false,
-      reason: `skill ${subdir} frontmatter parse failed: ${
-        cause instanceof Error ? cause.message : String(cause)
-      }`,
-    };
-  }
-
-  const result = skillFrontmatterSchema(parsed.frontmatter);
-  if (result instanceof type.errors) {
-    return {
-      ok: false,
-      reason: `skill ${subdir} frontmatter is invalid: ${result.summary}`,
-    };
-  }
-
-  if (result.name !== subdir) {
-    return {
-      ok: false,
-      reason: `skill ${subdir} frontmatter.name ${JSON.stringify(
-        result.name,
-      )} does not match directory name`,
-    };
-  }
-
-  return {
-    ok: true,
-    entry: {
-      name: result.name,
-      description: result.description,
-      frontmatter: parsed.frontmatter,
-      workspaceSubpath: `${subdir}/`,
-    },
-  };
-}
-
-async function buildSkillIndex(
-  topLevelTreePaths: string[],
-  readBlob: (path: string) => Promise<Uint8Array>,
-): Promise<
-  { ok: true; entries: SkillIndexEntry[] } | { ok: false; reason: string }
-> {
-  const entries: SkillIndexEntry[] = [];
-  // Sort so the index ordering is deterministic across reads.
-  const subdirs = [...topLevelTreePaths].sort();
-  for (const subdir of subdirs) {
-    const outcome = await parseSkillEntry(subdir, readBlob);
-    if (!outcome.ok) {
-      return { ok: false, reason: outcome.reason };
-    }
-    entries.push(outcome.entry);
-  }
-  return { ok: true, entries };
-}
-
-export const skillKindHandler: KindHandler = {
-  kind: "skill",
-  directoryPrefix: "assets/skill",
-  async validatePush({
-    repoId,
-    ref,
-    topLevelTreePaths,
-    readBlob,
-  }): Promise<ValidatePushResult> {
-    // Drop any staged entry from a previous attempt first. The
-    // substrate calls validatePush before advancing the ref, so a prior
-    // validation that was accepted but never followed by onRefUpdated
-    // (e.g. the commit step threw after validation succeeded) would
-    // otherwise leave a stale entry that a later rejected attempt
-    // would silently inherit.
-    const key = cacheKey(repoId.id, ref);
-    pendingIndex.delete(key);
-
-    const result = await buildSkillIndex(topLevelTreePaths, readBlob);
-    if (!result.ok) {
-      logger.debug`skill validatePush rejected ${repoId.kind}/${repoId.id} on ${ref}: ${result.reason}`;
-      return { ok: false, reason: result.reason };
-    }
-    // Stage the parsed index against (repoId.id, ref). The substrate
-    // calls onRefUpdated immediately after the ref is advanced and we
-    // promote the staged entry into the live cache there.
-    pendingIndex.set(key, result.entries);
-    return { ok: true };
-  },
-  onRefUpdated({ repoId, ref }) {
-    const key = cacheKey(repoId.id, ref);
-    const staged = pendingIndex.get(key);
-    if (staged === undefined) {
-      throw new Error(
-        `skillKindHandler.onRefUpdated: no validated tree pending for ${repoId.id} @ ${ref}`,
-      );
-    }
-    pendingIndex.delete(key);
-    skillIndex.set(key, staged);
-  },
-};
-
-const SidecarPrincipal = type({
-  kind: "'sidecar'",
-  agentId: "string",
-});
-
-export const skillAuthorize: AuthorizeFn = (
-  principal: Principal,
-  repoId,
-  ref,
-  action,
-) => {
-  if (repoId.kind !== "skill") {
-    return {
-      allowed: false,
-      reason: `skill authorize received non-skill repo ${repoId.kind}/${repoId.id}`,
-    };
-  }
-
-  if (principal.kind === "hub") {
-    return { allowed: true };
-  }
-
-  if (principal.kind === "sidecar") {
-    const parsed = SidecarPrincipal(principal);
-    if (parsed instanceof type.errors) {
-      return {
-        allowed: false,
-        reason: `sidecar principal is malformed: ${parsed.summary}`,
-      };
-    }
-    switch (action) {
-      case "createPack":
-      case "resolveRef":
-        return { allowed: true };
-      case "init":
-      case "writeTree":
-      case "receivePack":
-        return {
-          allowed: false,
-          reason: `sidecars may only read skill assets, not ${action}`,
-        };
-      default: {
-        const _exhaustive: never = action;
-        return {
-          allowed: false,
-          reason: `unhandled action: ${String(_exhaustive)}`,
-        };
-      }
-    }
-  }
-
-  if (principal.kind === "user") {
-    // The route layer has already pre-resolved the grant verdict and
-    // attached it as `authz`. The substrate does NOT re-query the
-    // grant store here; it (a) checks the bearer-token's claims
-    // bound the requested (ref, action) and have not expired, and
-    // (b) sanity-checks that the pre-resolved verdict targets this
-    // exact resource and grant verb. Both gates must pass before the
-    // verdict's `effect` is honoured.
-    const parsed = UserPrincipal(principal);
-    if (parsed instanceof type.errors) {
-      return {
-        allowed: false,
-        reason: `user principal is malformed: ${parsed.summary}`,
-      };
-    }
-    if (!parsed.tokenClaims.actions.includes(action)) {
-      return {
-        allowed: false,
-        reason: `token does not grant action ${action}`,
-      };
-    }
-    // `ref === "*"` is the substrate's sentinel for a bulk read used
-    // by `listRefs`. The advertise-refs layer applies the per-ref
-    // refPattern filter on the listing it returns, so gating the bulk
-    // read on refPattern here would prevent any token with a
-    // narrow-pattern (e.g. `refs/heads/main`) from listing refs at
-    // all. Only the action and expiry are enforced for the bulk read;
-    // every other call site passes a concrete ref and is gated below.
-    if (ref !== "*" && !glob.match(parsed.tokenClaims.refPattern, ref)) {
-      return {
-        allowed: false,
-        reason: `token refPattern ${parsed.tokenClaims.refPattern} does not match ${ref}`,
-      };
-    }
-    if (Date.now() >= parsed.tokenClaims.expiresAt) {
-      return {
-        allowed: false,
-        reason: `token expired at ${parsed.tokenClaims.expiresAt}`,
-      };
-    }
-    const expectedResource = `asset:${repoId.id}`;
-    if (parsed.authz.resource !== expectedResource) {
-      return {
-        allowed: false,
-        reason: `authz verdict resource ${parsed.authz.resource} does not match ${expectedResource}`,
-      };
-    }
-    const expectedGrantVerb = repoActionToGrantVerb(action);
-    if (parsed.authz.grantVerb !== expectedGrantVerb) {
-      return {
-        allowed: false,
-        reason: `authz verdict grantVerb ${parsed.authz.grantVerb} does not match ${expectedGrantVerb}`,
-      };
-    }
-    if (parsed.authz.effect === "allow") {
-      return { allowed: true };
-    }
-    return {
-      allowed: false,
-      reason: `authz verdict denied for ${expectedResource} ${expectedGrantVerb}`,
-    };
-  }
-
-  return {
-    allowed: false,
-    reason: `unknown principal kind: ${principal.kind}`,
-  };
-};

package/src/ws/index.ts

@@ -1,18 +0,0 @@
-export {
-  createSidecarRouter,
-  type SidecarRouter,
-  type SidecarRouterConfig,
-  type SidecarConnection,
-  type SendPackOptions,
-  type WsHandle,
-} from "./sidecar-handler";
-export {
-  createSidecarEmitter,
-  type SidecarEventEmitter,
-  type SidecarEventMap,
-  type SidecarEventType,
-  type SidecarEventListener,
-  type SidecarLookups,
-  type SidecarMailPersistedRow,
-  type SidecarMailPersistedPayload,
-} from "./sidecar-events";

package/src/ws/sidecar-events.test.ts

@@ -1,96 +0,0 @@
-import { describe, test, expect } from "bun:test";
-import { createSidecarEmitter } from "./sidecar-events";
-
-describe("createSidecarEmitter", () => {
-  test("delivers events to subscribed listeners", () => {
-    const emitter = createSidecarEmitter();
-    const seen: { addr: string; sid: string }[] = [];
-    emitter.on("agent.event", ({ agentAddress, sessionId }) => {
-      seen.push({ addr: agentAddress, sid: sessionId });
-    });
-
-    emitter.emit("agent.event", {
-      agentAddress: "a@x",
-      sessionId: "s-1",
-      event: { type: "x" },
-    });
-
-    expect(seen).toEqual([{ addr: "a@x", sid: "s-1" }]);
-  });
-
-  test("supports multiple listeners on the same event", () => {
-    const emitter = createSidecarEmitter();
-    const order: string[] = [];
-    emitter.on("sidecar.disconnect", () => {
-      order.push("a");
-    });
-    emitter.on("sidecar.disconnect", () => {
-      order.push("b");
-    });
-
-    emitter.emit("sidecar.disconnect", { agentAddresses: [] });
-
-    expect(order).toEqual(["a", "b"]);
-  });
-
-  test("unsubscribe removes the listener", () => {
-    const emitter = createSidecarEmitter();
-    let count = 0;
-    const unsubscribe = emitter.on("sidecar.disconnect", () => {
-      count++;
-    });
-
-    emitter.emit("sidecar.disconnect", { agentAddresses: [] });
-    unsubscribe();
-    emitter.emit("sidecar.disconnect", { agentAddresses: [] });
-
-    expect(count).toBe(1);
-  });
-
-  test("emit swallows listener errors and continues", () => {
-    const emitter = createSidecarEmitter();
-    const seen: string[] = [];
-    emitter.on("sidecar.disconnect", () => {
-      throw new Error("boom");
-    });
-    emitter.on("sidecar.disconnect", () => {
-      seen.push("ran");
-    });
-
-    emitter.emit("sidecar.disconnect", { agentAddresses: [] });
-
-    expect(seen).toEqual(["ran"]);
-  });
-
-  test("emitAndAwait runs listeners sequentially and rethrows the first failure", async () => {
-    const emitter = createSidecarEmitter();
-    const seen: string[] = [];
-    emitter.on("agent.reconnected", async () => {
-      seen.push("a");
-    });
-    emitter.on("agent.reconnected", async () => {
-      seen.push("b");
-      throw new Error("listener b failed");
-    });
-    emitter.on("agent.reconnected", async () => {
-      seen.push("c");
-    });
-
-    await expect(
-      emitter.emitAndAwait("agent.reconnected", { agentAddress: "a@x" }),
-    ).rejects.toThrow(/listener b failed/);
-
-    expect(seen).toEqual(["a", "b"]);
-  });
-
-  test("listenerCount reflects current subscriptions", () => {
-    const emitter = createSidecarEmitter();
-    expect(emitter.listenerCount("agent.reconnected")).toBe(0);
-
-    const off = emitter.on("agent.reconnected", () => undefined);
-    expect(emitter.listenerCount("agent.reconnected")).toBe(1);
-
-    off();
-    expect(emitter.listenerCount("agent.reconnected")).toBe(0);
-  });
-});

package/src/ws/sidecar-events.ts

@@ -1,231 +0,0 @@
-// Typed event emitter for the sidecar router.
-//
-// The router emits events at the points where wire-layer frame handling
-// completes and a host-side decision or side effect is required. Two
-// emission shapes are exposed:
-//
-// - `emit(type, payload)` — notification semantics. Each listener runs
-//   inside its own try/catch; a thrown error is logged and does not
-//   affect other listeners or the wire layer. Used for events whose
-//   outcome does not feed back into protocol behavior.
-//
-// - `emitAndAwait(type, payload)` — sequential await semantics.
-//   Listeners run in registration order; the first rejection propagates
-//   to the caller and stops the chain. Used for events whose outcome
-//   affects subsequent wire-layer state (e.g. reconnect rollback).
-//
-// The TSDoc on each entry in `SidecarEventMap` records which semantic
-// applies. Mixing the two on a single event is intentional: today's
-// wire layer already has both behaviors, and pretending otherwise
-// would silently change failure handling.
-
-import type { PackRejectReason, RepoId } from "@intx/types/sidecar";
-import type { ConnectorThreadState } from "@intx/types/runtime";
-import { getLogger } from "@intx/log";
-
-const logger = getLogger(["hub", "ws", "sidecar", "events"]);
-
-export type SidecarMailPersistedRow = {
-  id: string;
-  createdAt: Date;
-  direction: "inbound" | "outbound";
-  instanceId: string | null;
-  address: string;
-};
-
-export type SidecarMailPersistedPayload = SidecarMailPersistedRow & {
-  raw: Uint8Array;
-};
-
-export type SidecarEventMap = {
-  /** Notification. Emitted for every agent.event frame the wire layer
-   * decodes. The wire layer also forwards the event to in-process agent
-   * subscribers registered via `router.subscribeAgent`; this event is
-   * the host-side observation point. */
-  "agent.event": {
-    agentAddress: string;
-    sessionId: string;
-    event: unknown;
-  };
-
-  /** Notification. Emitted once when a sidecar's connection closes,
-   * carrying the set of agent addresses that were registered on that
-   * connection. */
-  "sidecar.disconnect": {
-    agentAddresses: string[];
-  };
-
-  /** Notification. Emitted when a mail.outbound frame from a sidecar
-   * names recipients that the wire layer could not deliver locally and
-   * could not enqueue for a disconnected agent. The host is free to
-   * relay it onto an external transport or drop it. */
-  "mail.outbound.undelivered": {
-    rawMessage: string;
-    recipients: string[];
-  };
-
-  /** Notification. Emitted once per row produced by the host's
-   * `persistMail` lookup. The wire layer calls `persistMail` to obtain
-   * the rows; this event fires for each so subscribers can react
-   * per-row (e.g. dispatch a delivered event). */
-  "mail.persisted": SidecarMailPersistedPayload;
-
-  /** Awaited. Emitted when an agent.deploy.ack frame arrives. Rejection
-   * fails the pending deploy with the listener's error. */
-  "agent.deploy.ack": {
-    agentAddress: string;
-    publicKey: string;
-  };
-
-  /** Notification. Emitted when the sidecar reports a change to an
-   * agent's connector-thread state. The wire layer caches the state
-   * per agent so the host can read it via
-   * `router.getConnectorState(agentAddress)`; this event is for hosts
-   * that want to observe transitions directly. `connectorState` is
-   * `null` when the agent has no active connector thread. */
-  "connector.state.changed": {
-    agentAddress: string;
-    connectorState: ConnectorThreadState | null;
-  };
-
-  /** Awaited. Emitted per address after challenge verification
-   * succeeds and before the disconnect queue is flushed. Rejection
-   * rolls that address back from the routing table; earlier listeners
-   * in registration order have already executed and their side effects
-   * are not undone. A subsequent reconnect arriving mid-flight may
-   * supersede this one, so listeners must be idempotent. */
-  "agent.reconnected": {
-    agentAddress: string;
-  };
-
-  /** Awaited. Emitted per address after the wire layer has confirmed
-   * the sidecar's deploy ref is stale relative to the hub's current
-   * ref. The listener's job is to push a fresh deploy pack. The wire
-   * layer fires this only when staleness is confirmed; subscribing
-   * without a `lookupDeployRef` configured on the router will never
-   * deliver. */
-  "deploy.ref.stale": {
-    agentAddress: string;
-  };
-};
-
-export type SidecarEventType = keyof SidecarEventMap;
-
-export type SidecarEventListener<T extends SidecarEventType> = (
-  payload: SidecarEventMap[T],
-) => void | Promise<void>;
-
-export type SidecarEventEmitter = {
-  on<T extends SidecarEventType>(
-    type: T,
-    listener: SidecarEventListener<T>,
-  ): () => void;
-  emit<T extends SidecarEventType>(type: T, payload: SidecarEventMap[T]): void;
-  emitAndAwait<T extends SidecarEventType>(
-    type: T,
-    payload: SidecarEventMap[T],
-  ): Promise<void>;
-  /** Number of listeners registered for `type`. Wire-layer callers use
-   * this to skip an `await` when nothing is listening, preserving the
-   * synchronous scheduling of unconfigured-handler paths. */
-  listenerCount(type: SidecarEventType): number;
-};
-
-export function createSidecarEmitter(): SidecarEventEmitter {
-  const listeners: { [K in SidecarEventType]: Set<SidecarEventListener<K>> } = {
-    "agent.event": new Set(),
-    "sidecar.disconnect": new Set(),
-    "mail.outbound.undelivered": new Set(),
-    "mail.persisted": new Set(),
-    "agent.deploy.ack": new Set(),
-    "agent.reconnected": new Set(),
-    "deploy.ref.stale": new Set(),
-    "connector.state.changed": new Set(),
-  };
-
-  function on<T extends SidecarEventType>(
-    type: T,
-    listener: SidecarEventListener<T>,
-  ): () => void {
-    listeners[type].add(listener);
-    return () => {
-      listeners[type].delete(listener);
-    };
-  }
-
-  function emit<T extends SidecarEventType>(
-    type: T,
-    payload: SidecarEventMap[T],
-  ): void {
-    const set = listeners[type];
-    if (set.size === 0) return;
-    for (const listener of [...set]) {
-      try {
-        const result = listener(payload);
-        if (result instanceof Promise) {
-          result.catch((err: unknown) => {
-            logger.warn`Listener for ${type} threw: ${
-              err instanceof Error ? err.message : String(err)
-            }`;
-          });
-        }
-      } catch (err) {
-        logger.warn`Listener for ${type} threw: ${
-          err instanceof Error ? err.message : String(err)
-        }`;
-      }
-    }
-  }
-
-  async function emitAndAwait<T extends SidecarEventType>(
-    type: T,
-    payload: SidecarEventMap[T],
-  ): Promise<void> {
-    const set = listeners[type];
-    if (set.size === 0) return;
-    for (const listener of [...set]) {
-      await listener(payload);
-    }
-  }
-
-  function listenerCount(type: SidecarEventType): number {
-    return listeners[type].size;
-  }
-
-  return { on, emit, emitAndAwait, listenerCount };
-}
-
-export type SidecarLookups = {
-  /** Returns the hex-encoded Ed25519 public key stored for the address,
-   * or `null` if the address is unknown. Used during the reconnect
-   * challenge to verify the sidecar's signature. */
-  lookupPublicKey?: (agentAddress: string) => Promise<string | null>;
-
-  /** Returns the hub's current deploy ref for the address, or `null` if
-   * no deploy state is tracked. The wire layer compares this against
-   * the sidecar's reported ref during reconnect and emits
-   * `deploy.ref.stale` only on mismatch. */
-  lookupDeployRef?: (agentAddress: string) => Promise<string | null>;
-
-  /** Persists a delivered outbound mail frame. Returns one row per
-   * persisted record; the wire layer attaches `raw` to each row and
-   * emits a `mail.persisted` event. */
-  persistMail?: (args: {
-    senderAddress: string;
-    recipients: string[];
-    raw: Uint8Array;
-  }) => Promise<SidecarMailPersistedRow[]>;
-
-  /** Ingests a received state pack and returns whether the wire layer
-   * should ack or reject the pack to the sidecar. `repoId` identifies the
-   * source repo at the hub (e.g. `{ kind: "agent-state", id: agentAddress }`
-   * for the agent-state flow). */
-  receiveStatePack?: (
-    repoId: RepoId,
-    pack: Uint8Array,
-    ref: string,
-    commitSha: string,
-  ) => Promise<
-    { accepted: true } | { accepted: false; reason: PackRejectReason }
-  >;
-};