@intx/hub-sessions 0.1.2

package/src/asset-service.ts

@@ -0,0 +1,378 @@
+// In-process service for creating and attaching skill-asset repos.
+//
+// Three responsibilities are layered here, mirroring the substrate's
+// own layering (DB row, repo bookkeeping, content validation):
+//
+//   createAsset    inserts the asset row and initializes an empty
+//                  skill-kind repo via RepoStore.initRepo.
+//   populateAsset  drives RepoStore.writeTree, which runs the kind
+//                  handler's validatePush before advancing the ref.
+//                  Content rejections surface as AssetValidationError.
+//   attachAsset    inserts an agent_asset row, surfacing the
+//                  (agentId, assetId) uniqueness violation (which
+//                  prevents the same asset being attached to one
+//                  agent twice) as AssetAttachError.
+//
+// The factory is closure-based to match createAgentRepoStore and
+// createRepoStore. There is no class because there is no per-instance
+// mutable state — every method is a pure function over the deps.
+
+import { asc, eq } from "drizzle-orm";
+import { type DB } from "@intx/db";
+import {
+  agentAsset as agentAssetTable,
+  asset as assetTable,
+} from "@intx/db/schema";
+import { generateId } from "@intx/hub-common";
+import { getLogger } from "@intx/log";
+import { hasCode } from "@intx/types";
+import type { RepoKind } from "@intx/types/sidecar";
+
+import type {
+  InitRepoOpts,
+  Principal,
+  RepoStore,
+  TreeContent,
+} from "./repo-store";
+
+const logger = getLogger(["hub-sessions", "asset-service"]);
+
+// Postgres SQLSTATE codes. drizzle / postgres-js surfaces the original
+// error with `code` set; `hasCode` narrows safely.
+const PG_UNIQUE_VIOLATION = "23505";
+const PG_FOREIGN_KEY_VIOLATION = "23503";
+
+export type Asset = {
+  id: string;
+  tenantId: string;
+  kind: RepoKind;
+  name: string;
+  displayName: string | null;
+  creatorPrincipalId: string | null;
+  createdAt: Date;
+  updatedAt: Date;
+};
+
+export type AccessMode = "read-only" | "read-write";
+
+export type AgentAsset = {
+  id: string;
+  agentId: string;
+  assetId: string;
+  ref: string;
+  accessMode: AccessMode;
+  createdAt: Date;
+};
+
+export type AgentAssetWithAsset = AgentAsset & {
+  asset: Pick<Asset, "id" | "tenantId" | "kind" | "name" | "displayName">;
+};
+
+export type CreateAssetParams = {
+  tenantId: string;
+  /** Only "skill" is supported. "agent-state" is rejected because those
+   * repos are managed by the agent lifecycle, not the asset service. */
+  kind: RepoKind;
+  name: string;
+  displayName?: string;
+  creatorPrincipalId?: string;
+  /** Forwarded verbatim to `repoStore.initRepo`. Lets the REST route
+   * layer ship a per-asset `.gitignore` body (OS/editor cruft + build
+   * artefacts + `keys/`) in the genesis tree without the service
+   * encoding policy for any one consumer. When omitted, the substrate
+   * default body applies. */
+  initOpts?: InitRepoOpts;
+};
+
+export type PopulateAssetParams = {
+  assetId: string;
+  ref: string;
+  tree: TreeContent;
+  /** The principal authorized to write the kind. The substrate's
+   * authorize gate uses this; the kind handler also relies on it
+   * (e.g. skillAuthorize only permits `kind: "hub"` writes). */
+  principal: Principal;
+};
+
+export type AttachAssetParams = {
+  agentId: string;
+  assetId: string;
+  ref: string;
+  accessMode?: AccessMode;
+};
+
+export interface AssetService {
+  createAsset(params: CreateAssetParams): Promise<Asset>;
+  populateAsset(params: PopulateAssetParams): Promise<{ commitSha: string }>;
+  attachAsset(params: AttachAssetParams): Promise<AgentAsset>;
+  listAgentAssets(agentId: string): Promise<AgentAssetWithAsset[]>;
+}
+
+/** Discriminator for AssetServiceError variants. Lets callers branch
+ * without instanceof gymnastics across the different error subclasses. */
+export type AssetServiceErrorReason =
+  | "unsupported_kind"
+  | "duplicate_asset"
+  | "duplicate_attachment"
+  | "invalid_name"
+  | "invalid_reference"
+  | "not_found"
+  | "path_violation";
+
+// Asset names become the default workspace mountpath segment at
+// session start (`skills/<asset.name>/`). The mountpath segment
+// validator in applyAssetPack rejects anything outside a safe
+// character set; validate at the createAsset boundary so a bad name
+// fails at creation time rather than at materialization time. Names
+// must be lowercase-kebab: lowercase letters, digits, hyphens, with
+// no leading or trailing hyphen.
+const ASSET_NAME_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+export class AssetServiceError extends Error {
+  readonly reason: AssetServiceErrorReason;
+
+  constructor(
+    reason: AssetServiceErrorReason,
+    message: string,
+    cause?: unknown,
+  ) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = "AssetServiceError";
+    this.reason = reason;
+  }
+}
+
+function isAccessMode(value: string): value is AccessMode {
+  return value === "read-only" || value === "read-write";
+}
+
+function rowToAsset(row: typeof assetTable.$inferSelect): Asset {
+  // The schema stores `kind` as plain text. RepoKind is an arktype
+  // enum of ("agent-state" | "skill"); narrow by exhaustive check so
+  // an out-of-band kind value loudly fails rather than silently
+  // mistypes the returned shape.
+  let narrowed: RepoKind;
+  switch (row.kind) {
+    case "agent-state":
+      narrowed = "agent-state";
+      break;
+    case "skill":
+      narrowed = "skill";
+      break;
+    default:
+      throw new Error(
+        `asset row ${row.id} has unknown kind ${JSON.stringify(row.kind)}`,
+      );
+  }
+  return {
+    id: row.id,
+    tenantId: row.tenantId,
+    kind: narrowed,
+    name: row.name,
+    displayName: row.displayName,
+    creatorPrincipalId: row.creatorPrincipalId,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt,
+  };
+}
+
+function rowToAgentAsset(row: typeof agentAssetTable.$inferSelect): AgentAsset {
+  if (!isAccessMode(row.accessMode)) {
+    throw new Error(
+      `agent_asset row ${row.id} has unknown accessMode ${JSON.stringify(row.accessMode)}`,
+    );
+  }
+  return {
+    id: row.id,
+    agentId: row.agentId,
+    assetId: row.assetId,
+    ref: row.ref,
+    accessMode: row.accessMode,
+    createdAt: row.createdAt,
+  };
+}
+
+export function createAssetService(deps: {
+  // only the drizzle handle is needed, not the connection pool — symmetric
+  // with createHubSessionLookups and its sibling services.
+  db: DB["db"];
+  repoStore: RepoStore;
+}): AssetService {
+  const { db, repoStore } = deps;
+
+  async function createAsset(params: CreateAssetParams): Promise<Asset> {
+    if (params.kind === "agent-state") {
+      throw new AssetServiceError(
+        "unsupported_kind",
+        `createAsset rejects kind "agent-state": agent-state repos are managed by the agent lifecycle, not the asset service`,
+      );
+    }
+
+    if (!ASSET_NAME_PATTERN.test(params.name)) {
+      throw new AssetServiceError(
+        "invalid_name",
+        `createAsset rejects name ${JSON.stringify(
+          params.name,
+        )}: must be lowercase-kebab (letters, digits, hyphens; no leading or trailing hyphen)`,
+      );
+    }
+
+    const id = generateId("asset");
+    const now = new Date();
+    const insertRow = {
+      id,
+      tenantId: params.tenantId,
+      kind: params.kind,
+      name: params.name,
+      displayName: params.displayName ?? null,
+      creatorPrincipalId: params.creatorPrincipalId ?? null,
+      createdAt: now,
+      updatedAt: now,
+    };
+
+    // Init the repo before the row insert so a repo-init failure leaves
+    // no orphan row in the database. initRepo is idempotent and the
+    // generated id is locally unique, so a follow-up failure of the row
+    // insert (duplicate, FK violation, etc.) leaves at worst an empty
+    // unreferenced repo directory — harmless and reused on retry of a
+    // logically identical asset. The asset-service db handle does not
+    // expose transactions in the current narrowing, so this ordering is
+    // the safest cross-cutting fix without widening the dep surface.
+    await repoStore.initRepo({ kind: params.kind, id }, params.initOpts);
+
+    let inserted: typeof assetTable.$inferSelect;
+    try {
+      const rows = await db.insert(assetTable).values(insertRow).returning();
+      const row = rows[0];
+      if (row === undefined) {
+        throw new Error("insert into asset returned no rows");
+      }
+      inserted = row;
+    } catch (err) {
+      if (hasCode(err) && err.code === PG_UNIQUE_VIOLATION) {
+        throw new AssetServiceError(
+          "duplicate_asset",
+          `asset (tenantId=${params.tenantId}, kind=${params.kind}, name=${params.name}) already exists`,
+          err,
+        );
+      }
+      throw err;
+    }
+
+    logger.debug`created asset ${id} (kind=${params.kind}, tenant=${params.tenantId}, name=${params.name})`;
+
+    return rowToAsset(inserted);
+  }
+
+  async function populateAsset(
+    params: PopulateAssetParams,
+  ): Promise<{ commitSha: string }> {
+    // The asset row carries `kind`. We must read it before writing so
+    // the RepoId is shaped correctly; without it, callers could write
+    // against the wrong kind handler.
+    const row = await db.query.asset.findFirst({
+      where: eq(assetTable.id, params.assetId),
+    });
+    if (row === undefined) {
+      throw new AssetServiceError(
+        "not_found",
+        `populateAsset: asset ${params.assetId} not found`,
+      );
+    }
+    const assetRow = rowToAsset(row);
+
+    try {
+      return await repoStore.writeTree(
+        params.principal,
+        { kind: assetRow.kind, id: assetRow.id },
+        params.ref,
+        params.tree,
+      );
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      if (msg.startsWith("path_violation:")) {
+        throw new AssetServiceError("path_violation", msg, err);
+      }
+      throw err;
+    }
+  }
+
+  async function attachAsset(params: AttachAssetParams): Promise<AgentAsset> {
+    const id = generateId("agentAsset");
+    const accessMode = params.accessMode ?? "read-only";
+    const insertRow = {
+      id,
+      agentId: params.agentId,
+      assetId: params.assetId,
+      ref: params.ref,
+      accessMode,
+      createdAt: new Date(),
+    };
+
+    let inserted: typeof agentAssetTable.$inferSelect;
+    try {
+      const rows = await db
+        .insert(agentAssetTable)
+        .values(insertRow)
+        .returning();
+      const row = rows[0];
+      if (row === undefined) {
+        throw new Error("insert into agent_asset returned no rows");
+      }
+      inserted = row;
+    } catch (err) {
+      if (hasCode(err) && err.code === PG_UNIQUE_VIOLATION) {
+        throw new AssetServiceError(
+          "duplicate_attachment",
+          `agent_asset (agentId=${params.agentId}, assetId=${params.assetId}) already attached`,
+          err,
+        );
+      }
+      if (hasCode(err) && err.code === PG_FOREIGN_KEY_VIOLATION) {
+        throw new AssetServiceError(
+          "invalid_reference",
+          `agent_asset (agentId=${params.agentId}, assetId=${params.assetId}) references a missing agent or asset`,
+          err,
+        );
+      }
+      throw err;
+    }
+
+    return rowToAgentAsset(inserted);
+  }
+
+  async function listAgentAssets(
+    agentId: string,
+  ): Promise<AgentAssetWithAsset[]> {
+    // Order by (createdAt, id) so the row sequence is stable across reads
+    // — the available_skills stanza and pack fan-out both depend on a
+    // deterministic order, and Postgres does not guarantee one without
+    // an explicit orderBy.
+    const rows = await db
+      .select({
+        agentAsset: agentAssetTable,
+        asset: assetTable,
+      })
+      .from(agentAssetTable)
+      .innerJoin(assetTable, eq(agentAssetTable.assetId, assetTable.id))
+      .where(eq(agentAssetTable.agentId, agentId))
+      .orderBy(asc(agentAssetTable.createdAt), asc(agentAssetTable.id));
+
+    return rows.map((row) => {
+      const aa = rowToAgentAsset(row.agentAsset);
+      const a = rowToAsset(row.asset);
+      return {
+        ...aa,
+        asset: {
+          id: a.id,
+          tenantId: a.tenantId,
+          kind: a.kind,
+          name: a.name,
+          displayName: a.displayName,
+        },
+      };
+    });
+  }
+
+  return { createAsset, populateAsset, attachAsset, listAgentAssets };
+}

package/src/available-skills-stanza.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect } from "bun:test";
+import {
+  buildAvailableSkillsStanza,
+  type AvailableSkillEntry,
+} from "./available-skills-stanza";
+
+describe("buildAvailableSkillsStanza", () => {
+  test("returns empty string when no entries are provided", () => {
+    expect(buildAvailableSkillsStanza([])).toBe("");
+  });
+
+  test("renders a single skill in the expected shape", () => {
+    const entries: AvailableSkillEntry[] = [
+      {
+        qualifiedName: "greeter/wave",
+        description: "Waves at the user.",
+        workspacePath: "workspace/skills/greeter/wave/",
+      },
+    ];
+    expect(buildAvailableSkillsStanza(entries)).toBe(
+      [
+        "<available_skills>",
+        "  <skill>",
+        "    <name>greeter/wave</name>",
+        "    <description>Waves at the user.</description>",
+        "    <path>workspace/skills/greeter/wave/</path>",
+        "  </skill>",
+        "</available_skills>",
+      ].join("\n"),
+    );
+  });
+
+  test("preserves declared order across multiple skills in one asset", () => {
+    const entries: AvailableSkillEntry[] = [
+      {
+        qualifiedName: "tools/alpha",
+        description: "First.",
+        workspacePath: "workspace/skills/tools/alpha/",
+      },
+      {
+        qualifiedName: "tools/beta",
+        description: "Second.",
+        workspacePath: "workspace/skills/tools/beta/",
+      },
+    ];
+    const out = buildAvailableSkillsStanza(entries);
+    const alphaIdx = out.indexOf("tools/alpha");
+    const betaIdx = out.indexOf("tools/beta");
+    expect(alphaIdx).toBeGreaterThan(-1);
+    expect(betaIdx).toBeGreaterThan(-1);
+    expect(alphaIdx).toBeLessThan(betaIdx);
+  });
+
+  test("qualifies same-named skills across distinct assets", () => {
+    const entries: AvailableSkillEntry[] = [
+      {
+        qualifiedName: "ops/deploy",
+        description: "Ops deploy.",
+        workspacePath: "workspace/skills/ops/deploy/",
+      },
+      {
+        qualifiedName: "web/deploy",
+        description: "Web deploy.",
+        workspacePath: "workspace/skills/web/deploy/",
+      },
+    ];
+    const out = buildAvailableSkillsStanza(entries);
+    expect(out).toContain("<name>ops/deploy</name>");
+    expect(out).toContain("<name>web/deploy</name>");
+  });
+
+  test("XML-escapes ampersands and angle brackets in field values", () => {
+    const entries: AvailableSkillEntry[] = [
+      {
+        qualifiedName: "tools/a&b",
+        description: "Handles A & B (with <stuff> too).",
+        workspacePath: "workspace/skills/tools/a&b/",
+      },
+    ];
+    const out = buildAvailableSkillsStanza(entries);
+    expect(out).toContain("<name>tools/a&amp;b</name>");
+    expect(out).toContain(
+      "<description>Handles A &amp; B (with &lt;stuff&gt; too).</description>",
+    );
+    expect(out).toContain("<path>workspace/skills/tools/a&amp;b/</path>");
+  });
+});

package/src/available-skills-stanza.ts

@@ -0,0 +1,47 @@
+export type AvailableSkillEntry = {
+  /** Qualified skill identifier in the form `<asset.name>/<skill-name>`. */
+  qualifiedName: string;
+  /** SKILL.md frontmatter description, verbatim. */
+  description: string;
+  /** Workspace-relative path the agent's `read_file` should target,
+   * shaped like `workspace/<mountPath>/<skill-name>/`. */
+  workspacePath: string;
+};
+
+/**
+ * Render the `<available_skills>` stanza appended to the agent's
+ * system prompt. Returns the empty string when `entries` is empty —
+ * an empty `<available_skills></available_skills>` wrapper would be
+ * misleading noise for agents with no skills attached.
+ *
+ * Values are XML-escaped at the boundary. The skill kind handler
+ * already rejects descriptions containing literal `<` or `>` so the
+ * `&` escape is the practical case in production; the others are
+ * defensive.
+ */
+export function buildAvailableSkillsStanza(
+  entries: AvailableSkillEntry[],
+): string {
+  if (entries.length === 0) {
+    return "";
+  }
+  const lines = ["<available_skills>"];
+  for (const entry of entries) {
+    lines.push("  <skill>");
+    lines.push(`    <name>${escapeXml(entry.qualifiedName)}</name>`);
+    lines.push(
+      `    <description>${escapeXml(entry.description)}</description>`,
+    );
+    lines.push(`    <path>${escapeXml(entry.workspacePath)}</path>`);
+    lines.push("  </skill>");
+  }
+  lines.push("</available_skills>");
+  return lines.join("\n");
+}
+
+function escapeXml(value: string): string {
+  return value
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;");
+}

package/src/credential-push.ts

@@ -0,0 +1,65 @@
+// Shared logic for pushing inference-source updates to sidecars.
+//
+// Used by the credentials PATCH route to broadcast updates to every running
+// instance in the tenant after a credential secret is rotated.
+
+import { eq, and } from "drizzle-orm";
+import { getLogger } from "@intx/log";
+import { agentInstance } from "@intx/db/schema";
+import { resolveInstanceSources } from "@intx/db";
+import type { DB } from "@intx/db";
+
+import type { SidecarRouter } from "./ws/sidecar-handler";
+
+const log = getLogger(["hub", "credentials"]);
+
+/**
+ * After a credential secret is rotated, find all running instances in the
+ * tenant that may use credentials from the affected provider, re-resolve
+ * their full sources array, and push updates to sidecars.
+ *
+ * Errors are logged per-instance but do not propagate.
+ *
+ * **Silent no-op when sources is empty.** `resolveInstanceSources`
+ * returns `[]` when an instance's agent has malformed
+ * `credentialRequirements` or `modelConfig`. This function skips those
+ * instances without emitting a log line of its own — the resolver's
+ * `db.credentials` logger is the only signal. When a credential rotation
+ * fails to reach an agent operators expect it to reach, grep the
+ * `db.credentials` logger for `Invalid modelConfig` or
+ * `Invalid credential requirements` warnings keyed on the agent id.
+ */
+export async function pushSourceUpdates(
+  db: DB["db"],
+  sidecarRouter: SidecarRouter,
+  tenantId: string,
+): Promise<void> {
+  const instances = await db.query.agentInstance.findMany({
+    where: and(
+      eq(agentInstance.tenantId, tenantId),
+      eq(agentInstance.status, "running"),
+    ),
+  });
+
+  if (instances.length === 0) return;
+
+  const results = await Promise.allSettled(
+    instances.map(async (instance) => {
+      const sources = await resolveInstanceSources(db, tenantId, instance);
+      if (sources.length === 0) return;
+      const [first] = sources;
+      if (first === undefined) return;
+      await sidecarRouter.sendSourcesUpdate(
+        instance.address,
+        sources,
+        first.id,
+      );
+    }),
+  );
+
+  for (const result of results) {
+    if (result.status === "rejected") {
+      log.warn`Failed to push source update: ${String(result.reason)}`;
+    }
+  }
+}

package/src/event-collector-registry.test.ts

@@ -0,0 +1,73 @@
+import { describe, test, expect } from "bun:test";
+import type { InferenceEvent } from "@intx/types/runtime";
+import { deriveStatus } from "./event-collector-registry";
+
+function event(
+  type: string,
+  data: Record<string, unknown> = {},
+): InferenceEvent {
+  // eslint-disable-next-line @typescript-eslint/no-unsafe-type-assertion -- test helper: type string is the correct discriminant
+  return { type, seq: 1, data } as InferenceEvent;
+}
+
+describe("deriveStatus", () => {
+  test("reactor.start does not set busy", () => {
+    expect(deriveStatus(event("reactor.start"))).toBeNull();
+  });
+
+  test("inference.start sets busy", () => {
+    expect(deriveStatus(event("inference.start", { model: "test" }))).toEqual({
+      status: "busy",
+    });
+  });
+
+  test("connector.reply sets idle", () => {
+    expect(deriveStatus(event("connector.reply", { content: "hi" }))).toEqual({
+      status: "idle",
+    });
+  });
+
+  test("reactor.done sets idle", () => {
+    expect(deriveStatus(event("reactor.done"))).toEqual({ status: "idle" });
+  });
+
+  test("reactor.gate.cleared sets busy", () => {
+    expect(
+      deriveStatus(event("reactor.gate.cleared", { gateId: "g1" })),
+    ).toEqual({ status: "busy" });
+  });
+
+  test("reactor.gate.blocked with approval sets waiting_approval", () => {
+    expect(
+      deriveStatus(
+        event("reactor.gate.blocked", { reason: "approval", gateId: "g1" }),
+      ),
+    ).toEqual({ status: "waiting_approval" });
+  });
+
+  test("reactor.gate.blocked with non-approval reason returns null", () => {
+    expect(
+      deriveStatus(
+        event("reactor.gate.blocked", { reason: "payment", gateId: "g1" }),
+      ),
+    ).toBeNull();
+  });
+
+  test("fatal reactor.error sets idle", () => {
+    expect(
+      deriveStatus(event("reactor.error", { error: "boom", fatal: true })),
+    ).toEqual({ status: "idle" });
+  });
+
+  test("non-fatal reactor.error returns null", () => {
+    expect(
+      deriveStatus(event("reactor.error", { error: "oops", fatal: false })),
+    ).toBeNull();
+  });
+
+  test("unrecognized event returns null", () => {
+    expect(
+      deriveStatus(event("inference.text.delta", { token: "hi" })),
+    ).toBeNull();
+  });
+});