@intx/hub-sessions 0.1.2

package/README.md

@@ -0,0 +1,26 @@
+# @intx/hub-sessions
+
+Session-orchestration substrate for the hub. Owns the sidecar
+WebSocket router, the session service that provisions and tears
+down agent sessions, the agent repository store, the event
+collector registry, the asset service, and the skill kind handler.
+
+Sits between `@intx/hub-api` (HTTP surface) and `@intx/hub-agent`
+(sidecar orchestrator): HTTP routes call into the session service
+to start an agent, the session service drives the sidecar router
+to provision it on the connected sidecar, and event collectors
+feed agent events back to the HTTP layer for observability.
+
+`createSessionService` takes a `SessionServiceDeps` of
+`sidecarRouter`, `agentRepoStore`, and an optional
+`assetService` paired with a `db` handle for the asset manifest
+inserts. `createHubSessionOrchestrator` takes a
+`HubSessionOrchestratorDeps` of `events`, `router`, `db`,
+`eventCollectors`, `grantStore`, and `agentRepoStore`. See the
+exported types in `src/session-service.ts` and
+`src/hub-session-orchestrator.ts` for the authoritative shapes;
+`@intx/hub-api` is the in-tree consumer that wires these
+factories together.
+
+The package does not host HTTP routes itself; it exposes the
+factories `@intx/hub-api` composes into the application.

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@intx/hub-sessions",
+  "version": "0.1.2",
+  "license": "LGPL-2.1-only",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.ts",
+      "default": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@intx/crypto-node": "0.0.0",
+    "@intx/db": "0.0.0",
+    "@intx/hub-common": "0.0.0",
+    "@intx/log": "0.0.0",
+    "@intx/mime": "0.0.0",
+    "@intx/pack-transport": "0.0.0",
+    "@intx/storage-isogit": "0.0.0",
+    "@intx/types": "0.0.0",
+    "arktype": "^2.1.29"
+  }
+}

package/src/agent-repo.test.ts

@@ -0,0 +1,310 @@
+import { describe, test, expect, afterAll, beforeAll } from "bun:test";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import git from "isomorphic-git";
+import { generateKeyPair } from "@intx/crypto-node";
+import { createDeployPack } from "@intx/storage-isogit";
+import { createAgentRepoStore } from "./agent-repo";
+import type { KeyPair } from "@intx/types/runtime";
+
+const tempDirs: string[] = [];
+
+async function makeTempDir(prefix: string): Promise<string> {
+  const d = await fs.promises.mkdtemp(path.join(os.tmpdir(), prefix));
+  tempDirs.push(d);
+  return d;
+}
+
+let signingKey: KeyPair;
+
+beforeAll(async () => {
+  signingKey = await generateKeyPair();
+});
+
+afterAll(async () => {
+  for (const d of tempDirs.splice(0)) {
+    await fs.promises.rm(d, { recursive: true, force: true }).catch((_e) => {
+      /* best effort cleanup */
+    });
+  }
+});
+
+describe("AgentRepoStore", () => {
+  test("writeDeployTree creates a commit with the system prompt", async () => {
+    const dataDir = await makeTempDir("agent-repo-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    const { commitSha } = await store.writeDeployTree("agent-1", {
+      systemPrompt: "You are a test agent.",
+    });
+
+    expect(commitSha).toMatch(/^[0-9a-f]{40}$/);
+
+    const repoDir = path.join(dataDir, "agents", "agent-1");
+    const prompt = await fs.promises.readFile(
+      path.join(repoDir, "deploy", "prompt.md"),
+      "utf-8",
+    );
+    expect(prompt).toBe("You are a test agent.");
+
+    const ref = await git.resolveRef({
+      fs,
+      dir: repoDir,
+      ref: "refs/heads/deploy",
+    });
+    expect(ref).toBe(commitSha);
+  });
+
+  test("writeDeployTree does not advance refs/heads/main", async () => {
+    const dataDir = await makeTempDir("agent-repo-ref-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    await store.writeDeployTree("agent-ref", {
+      systemPrompt: "Ref test.",
+    });
+
+    const repoDir = path.join(dataDir, "agents", "agent-ref");
+    const mainLog = await git.log({ fs, dir: repoDir, ref: "refs/heads/main" });
+    const deployLog = await git.log({
+      fs,
+      dir: repoDir,
+      ref: "refs/heads/deploy",
+    });
+
+    // main should only have the init commit
+    expect(mainLog.length).toBe(1);
+    // deploy should have 2: init parent + deploy commit
+    expect(deployLog.length).toBe(2);
+  });
+
+  test("createDeployPack produces a valid packfile", async () => {
+    const dataDir = await makeTempDir("agent-repo-pack-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    await store.writeDeployTree("agent-2", {
+      systemPrompt: "Pack test.",
+    });
+
+    const { pack, commitSha, ref } = await store.createDeployPack("agent-2");
+
+    expect(pack).toBeInstanceOf(Uint8Array);
+    expect(pack.length).toBeGreaterThan(0);
+    expect(commitSha).toMatch(/^[0-9a-f]{40}$/);
+    expect(ref).toBe("refs/heads/deploy");
+  });
+
+  test("receiveStatePack indexes objects and updates ref", async () => {
+    const dataDir = await makeTempDir("agent-repo-state-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    await store.writeDeployTree("agent-3", {
+      systemPrompt: "State test.",
+    });
+
+    const sourceDir = await makeTempDir("state-source-");
+    await git.init({ fs, dir: sourceDir, defaultBranch: "main" });
+    await fs.promises.mkdir(path.join(sourceDir, "state"), { recursive: true });
+    await fs.promises.writeFile(
+      path.join(sourceDir, "state", "turns.jsonl"),
+      '{"messages":[]}',
+    );
+    await git.add({ fs, dir: sourceDir, filepath: "state/turns.jsonl" });
+    const stateCommit = await git.commit({
+      fs,
+      dir: sourceDir,
+      message: "State snapshot",
+      author: { name: "test", email: "test@test" },
+    });
+
+    const { pack } = await createDeployPack(sourceDir, "refs/heads/main");
+
+    const stateRef = "refs/instances/test-instance";
+    await store.receiveStatePack(
+      { kind: "agent-state", id: "agent-3" },
+      pack,
+      stateRef,
+      stateCommit,
+    );
+
+    const repoDir = path.join(dataDir, "agents", "agent-3");
+    const resolved = await git.resolveRef({
+      fs,
+      dir: repoDir,
+      ref: stateRef,
+    });
+    expect(resolved).toBe(stateCommit);
+  });
+
+  test("receiveStatePack accepts packs with .gitignore alongside state", async () => {
+    const dataDir = await makeTempDir("agent-repo-gitignore-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    await store.writeDeployTree("agent-gi", {
+      systemPrompt: "Gitignore test.",
+    });
+
+    const sourceDir = await makeTempDir("gitignore-source-");
+    await git.init({ fs, dir: sourceDir, defaultBranch: "main" });
+    await fs.promises.writeFile(path.join(sourceDir, ".gitignore"), "keys/\n");
+    await fs.promises.mkdir(path.join(sourceDir, "state"), { recursive: true });
+    await fs.promises.writeFile(
+      path.join(sourceDir, "state", "turns.jsonl"),
+      "{}",
+    );
+    await git.add({ fs, dir: sourceDir, filepath: ".gitignore" });
+    await git.add({ fs, dir: sourceDir, filepath: "state/turns.jsonl" });
+    const stateCommit = await git.commit({
+      fs,
+      dir: sourceDir,
+      message: "State with gitignore",
+      author: { name: "test", email: "test@test" },
+    });
+
+    const { pack } = await createDeployPack(sourceDir, "refs/heads/main");
+    const stateRef = "refs/instances/gi-test";
+    await store.receiveStatePack(
+      { kind: "agent-state", id: "agent-gi" },
+      pack,
+      stateRef,
+      stateCommit,
+    );
+
+    const repoDir = path.join(dataDir, "agents", "agent-gi");
+    const resolved = await git.resolveRef({
+      fs,
+      dir: repoDir,
+      ref: stateRef,
+    });
+    expect(resolved).toBe(stateCommit);
+  });
+
+  test("receiveStatePack rejects packs with only .gitignore and no state/", async () => {
+    const dataDir = await makeTempDir("agent-repo-gitignore-only-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    await store.writeDeployTree("agent-gio", {
+      systemPrompt: "Gitignore-only test.",
+    });
+
+    const sourceDir = await makeTempDir("gitignore-only-source-");
+    await git.init({ fs, dir: sourceDir, defaultBranch: "main" });
+    await fs.promises.writeFile(path.join(sourceDir, ".gitignore"), "keys/\n");
+    await git.add({ fs, dir: sourceDir, filepath: ".gitignore" });
+    const badCommit = await git.commit({
+      fs,
+      dir: sourceDir,
+      message: "Only gitignore",
+      author: { name: "test", email: "test@test" },
+    });
+
+    const { pack } = await createDeployPack(sourceDir, "refs/heads/main");
+
+    await expect(
+      store.receiveStatePack(
+        { kind: "agent-state", id: "agent-gio" },
+        pack,
+        "refs/instances/test",
+        badCommit,
+      ),
+    ).rejects.toThrow("path_violation");
+  });
+
+  test("receiveStatePack rejects packs with paths outside state/", async () => {
+    const dataDir = await makeTempDir("agent-repo-confined-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    await store.writeDeployTree("agent-confined", {
+      systemPrompt: "Confinement test.",
+    });
+
+    const sourceDir = await makeTempDir("confined-source-");
+    await git.init({ fs, dir: sourceDir, defaultBranch: "main" });
+    await fs.promises.mkdir(path.join(sourceDir, "state"), { recursive: true });
+    await fs.promises.mkdir(path.join(sourceDir, "deploy"), {
+      recursive: true,
+    });
+    await fs.promises.writeFile(
+      path.join(sourceDir, "state", "turns.jsonl"),
+      "{}",
+    );
+    await fs.promises.writeFile(
+      path.join(sourceDir, "deploy", "prompt.md"),
+      "evil",
+    );
+    await git.add({ fs, dir: sourceDir, filepath: "state/turns.jsonl" });
+    await git.add({ fs, dir: sourceDir, filepath: "deploy/prompt.md" });
+    const badCommit = await git.commit({
+      fs,
+      dir: sourceDir,
+      message: "Escaped confinement",
+      author: { name: "test", email: "test@test" },
+    });
+
+    const { pack } = await createDeployPack(sourceDir, "refs/heads/main");
+
+    await expect(
+      store.receiveStatePack(
+        { kind: "agent-state", id: "agent-confined" },
+        pack,
+        "refs/instances/test",
+        badCommit,
+      ),
+    ).rejects.toThrow("path_violation");
+  });
+
+  test("writeDeployTree produces a fresh commit when content changes", async () => {
+    const dataDir = await makeTempDir("agent-repo-idem-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    const first = await store.writeDeployTree("agent-4", {
+      systemPrompt: "Version 1",
+    });
+
+    const second = await store.writeDeployTree("agent-4", {
+      systemPrompt: "Version 2",
+    });
+
+    expect(second.commitSha).not.toBe(first.commitSha);
+
+    const repoDir = path.join(dataDir, "agents", "agent-4");
+    const prompt = await fs.promises.readFile(
+      path.join(repoDir, "deploy", "prompt.md"),
+      "utf-8",
+    );
+    expect(prompt).toBe("Version 2");
+  });
+
+  test("hub repo does not contain state/ scaffolding", async () => {
+    const dataDir = await makeTempDir("agent-repo-nostate-");
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    await store.writeDeployTree("agent-5", {
+      systemPrompt: "No state test.",
+    });
+
+    const repoDir = path.join(dataDir, "agents", "agent-5");
+    const stateExists = await fs.promises
+      .stat(path.join(repoDir, "state"))
+      .then(() => true)
+      .catch(() => false);
+    expect(stateExists).toBe(false);
+  });
+
+  test("rejects agent IDs with path traversal characters", () => {
+    const dataDir = "/tmp/never-created";
+    const store = createAgentRepoStore({ dataDir, signingKey });
+
+    expect(() =>
+      store.writeDeployTree("../../evil", {
+        systemPrompt: "x",
+      }),
+    ).toThrow("repo_id_invalid: ../../evil");
+
+    expect(() =>
+      store.writeDeployTree("agent@domain", {
+        systemPrompt: "x",
+      }),
+    ).toThrow("repo_id_invalid: agent@domain");
+  });
+});

package/src/agent-repo.ts

@@ -0,0 +1,165 @@
+import { createSSHSignature } from "@intx/crypto-node";
+
+import { createRepoStore } from "./repo-store";
+import type { AuthorizeFn, RepoId, RepoStore } from "./repo-store";
+import {
+  agentStateKindHandler,
+  agentStateAuthorize,
+  AGENT_STATE_DEPLOY_REF,
+  type AgentStateHubPrincipal,
+  type AgentStateSidecarPrincipal,
+} from "./agent-state-kind";
+import { skillKindHandler, skillAuthorize } from "./skill-kind";
+
+export type DeployContent = {
+  systemPrompt: string;
+};
+
+export type AgentRepoStore = {
+  /**
+   * Write deploy content into the agent's hub-side repo and commit on
+   * refs/heads/deploy. Creates the repo if it doesn't exist.
+   *
+   * The caller is responsible for serializing calls per agent.
+   */
+  writeDeployTree(
+    agentId: string,
+    content: DeployContent,
+  ): Promise<{ commitSha: string }>;
+
+  /**
+   * Produce a packfile from the agent's current deploy ref.
+   */
+  createDeployPack(
+    agentId: string,
+  ): Promise<{ pack: Uint8Array; commitSha: string; ref: string }>;
+
+  /**
+   * Receive and store a state pack from a sidecar. Indexes the pack
+   * objects and updates the ref without materializing a working tree.
+   *
+   * `repoId.kind` must be `"agent-state"` — this store is per-agent and
+   * does not generalize across kinds. The `repoId.id` is used as the
+   * agent address internally.
+   */
+  receiveStatePack(
+    repoId: RepoId,
+    pack: Uint8Array,
+    ref: string,
+    commitSha: string,
+  ): Promise<void>;
+
+  /** Resolve the current deploy ref SHA, or null if no deploy exists. */
+  getDeployRef(agentId: string): Promise<string | null>;
+
+  /** Raw 32-byte Ed25519 public key used to sign deploy commits. */
+  getSigningPublicKey(): Uint8Array;
+
+  /**
+   * Underlying kind-keyed substrate. Exposed so callers that need to
+   * operate on non-agent-state kinds (e.g. the asset service writing
+   * skill repos) can share the same on-disk root and signing key
+   * without spinning up a parallel RepoStore.
+   */
+  readonly repoStore: RepoStore;
+};
+
+export function createAgentRepoStore(config: {
+  dataDir: string;
+  signingKey: { privateKey: Uint8Array; publicKey: Uint8Array };
+}): AgentRepoStore {
+  const { dataDir, signingKey } = config;
+
+  const authorize: AuthorizeFn = (principal, incomingRepoId, ref, action) => {
+    switch (incomingRepoId.kind) {
+      case "agent-state":
+        return agentStateAuthorize(principal, incomingRepoId, ref, action);
+      case "skill":
+        return skillAuthorize(principal, incomingRepoId, ref, action);
+      default: {
+        const _exhaustive: never = incomingRepoId.kind;
+        return {
+          allowed: false,
+          reason: `no authorize registered for kind: ${String(_exhaustive)}`,
+        };
+      }
+    }
+  };
+
+  // The substrate's signingCallback bridges the agent-repo store's
+  // raw Ed25519 keypair to the storage layer's per-payload SSHSIG
+  // signer. Skill asset genesis commits and agent-state deploy
+  // commits both flow through this signer so that signed commits
+  // round-trip through the smart-HTTP layer and verify under
+  // `git log --show-signature` and `git verify-commit`.
+  const signer = async (payload: string) =>
+    createSSHSignature(payload, signingKey.privateKey, signingKey.publicKey);
+
+  const store = createRepoStore({
+    dataDir,
+    signingKey,
+    handlers: {
+      "agent-state": agentStateKindHandler,
+      skill: skillKindHandler,
+    },
+    authorize,
+    signingCallback: () => signer,
+  });
+
+  const hub: AgentStateHubPrincipal = { kind: "hub" };
+
+  function repoId(agentId: string): RepoId {
+    return { kind: "agent-state", id: agentId };
+  }
+
+  return {
+    async writeDeployTree(agentId, content) {
+      const id = repoId(agentId);
+      const files: Record<string, string> = {
+        "deploy/prompt.md": content.systemPrompt,
+      };
+      return store.writeTree(hub, id, AGENT_STATE_DEPLOY_REF, {
+        files,
+        clearPrefix: "deploy/",
+        message: "Update deploy tree",
+      });
+    },
+
+    async createDeployPack(agentId) {
+      return store.createPack(hub, repoId(agentId), AGENT_STATE_DEPLOY_REF);
+    },
+
+    async receiveStatePack(incomingRepoId, pack, ref, commitSha) {
+      if (incomingRepoId.kind !== "agent-state") {
+        throw new Error(
+          `AgentRepoStore.receiveStatePack requires repoId.kind === "agent-state", got ${JSON.stringify(incomingRepoId.kind)}`,
+        );
+      }
+      const agentId = incomingRepoId.id;
+      const id = repoId(agentId);
+      const principal: AgentStateSidecarPrincipal = {
+        kind: "sidecar",
+        agentId,
+      };
+      const expectedOldSha = await store.resolveRef(principal, id, ref);
+      await store.receivePack(
+        principal,
+        id,
+        ref,
+        pack,
+        commitSha,
+        expectedOldSha,
+      );
+    },
+
+    async getDeployRef(agentId) {
+      return store.resolveRef(hub, repoId(agentId), AGENT_STATE_DEPLOY_REF);
+    },
+
+    getSigningPublicKey() {
+      return signingKey.publicKey;
+    },
+
+    repoStore: store,
+  };
+}