@vgalletti/hermes-office 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Victor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,86 @@
+# Hermes Office
+
+Hermes Office is a Next.js-powered visual workspace for Hermes Agent activity.
+It is a companion surface for an admin dashboard: Hermes Workspace remains the
+operational console for chat, sessions, configuration, jobs, and costs.
+
+## Goals
+
+- Render Hermes agents as visible characters in a pixel office.
+- Consume normalized Hermes snapshots and server-sent events without polling.
+- Keep Hermes secrets and dashboard tokens on the server side.
+- Ship a reusable React package named `hermes-office`.
+
+## Architecture
+
+```text
+Hermes API / Workspace events
+        -> Admin backend adapter
+        -> authenticated SSE endpoint
+        -> Hermes Office React renderer
+```
+
+The current public contract accepts `HermesAgent` snapshots and incremental
+`OfficeEvent` messages. The adapter is intentionally separate from the visual
+renderer so the UI does not depend on Hermes internal files or credentials.
+
+## Pixel Agents attribution
+
+This project vendors the Pixel Agents webview renderer under
+`vendor/pixel-agents-webview`. The renderer and included assets are licensed
+under MIT by Pablo De Lucca. Their copyright and license are preserved in that
+directory and in `THIRD_PARTY_LICENSES_PIXEL_AGENTS.txt`.
+
+The vendored renderer is the source for the full office engine: tiles, layout,
+pathfinding, furniture, sprite animation, and character states. Hermes Office
+will replace its temporary demo renderer with an adapter over that engine.
+
+## Development
+
+```bash
+npm install
+npm run dev
+```
+
+Open `http://127.0.0.1:4173` for the Next.js demo.
+
+Useful checks:
+
+```bash
+npm run typecheck
+npm run build
+npm run demo:build
+```
+
+## Publishing
+
+The package name is `hermes-office`.
+
+```bash
+pnpm publish
+pnpm add hermes-office
+```
+
+The equivalent npm command is:
+
+```bash
+npm install hermes-office
+```
+
+## Event contract
+
+The backend exposes an authenticated SSE stream:
+
+```text
+event: snapshot
+data: {"agents":[...]}
+
+event: agent.updated
+data: {"agent":{...}}
+
+event: agent.removed
+data: {"id":"..."}
+```
+
+The visual layer does not poll. It renders the last valid snapshot while the
+SSE connection reconnects.

package/dist/HermesOffice.d.ts

@@ -0,0 +1,10 @@
+import type { HermesAgent, OfficeTheme } from "./types.js";
+export type HermesOfficeProps = {
+    agents?: HermesAgent[];
+    className?: string;
+    theme?: Partial<OfficeTheme>;
+    engineUrl?: string;
+    title?: string;
+    height?: string;
+};
+export declare function HermesOffice({ agents, className, engineUrl, title, height }: HermesOfficeProps): import("react").JSX.Element;

package/dist/HermesOffice.js

@@ -0,0 +1,27 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useRef } from "react";
+export function HermesOffice({ agents = [], className, engineUrl = "/hermes-office", title = "Hermes Office", height = "calc(100vh - 9rem)" }) {
+    const frameRef = useRef(null);
+    const source = `${engineUrl.replace(/\/$/, "")}/index.html?external=1`;
+    useEffect(() => {
+        const frame = frameRef.current;
+        if (!frame?.contentWindow)
+            return;
+        const timer = window.setTimeout(() => {
+            const send = (data) => frame.contentWindow?.postMessage(data, window.location.origin);
+            const ids = agents.map((_, index) => index + 1);
+            send({ type: "existingAgents", agents: ids });
+            agents.forEach((agent, index) => {
+                const id = index + 1;
+                send({ type: "agentTeamInfo", id, agentName: agent.name });
+                if (agent.activity === "waiting")
+                    send({ type: "agentStatus", id, status: "waiting", awaitingInput: true });
+                else if (agent.activity !== "idle")
+                    send({ type: "agentToolStart", id, toolId: `hermes-${agent.id}`, status: `${agent.activity}: ${agent.name}` });
+            });
+        }, 350);
+        return () => window.clearTimeout(timer);
+    }, [agents]);
+    return _jsx("section", { className: className, "aria-label": title, children: _jsx("iframe", { ref: frameRef, src: source, title: title, className: "block w-full border-0 bg-background", style: { height, minHeight: 760 }, allow: "clipboard-read; clipboard-write" }) });
+}

package/dist/event-source.d.ts

@@ -0,0 +1,2 @@
+import type { AgentEventSource } from "./types.js";
+export declare function createSseEventSource(url: string): AgentEventSource;

package/dist/event-source.js

@@ -0,0 +1,31 @@
+const eventTypes = ["snapshot", "agent.updated", "agent.removed"];
+export function createSseEventSource(url) {
+    return {
+        subscribe(onEvent) {
+            const source = new EventSource(url);
+            const listeners = eventTypes.map((type) => {
+                const listener = (message) => {
+                    try {
+                        const payload = JSON.parse(message.data);
+                        onEvent({ type, ...payload });
+                    }
+                    catch {
+                        // Ignore malformed events. The next server snapshot restores state.
+                    }
+                };
+                source.addEventListener(type, listener);
+                return { type, listener };
+            });
+            source.onerror = () => {
+                // EventSource reconnects by itself. Consumers should render the last
+                // valid snapshot while the connection is recovering.
+            };
+            return () => {
+                for (const { type, listener } of listeners) {
+                    source.removeEventListener(type, listener);
+                }
+                source.close();
+            };
+        },
+    };
+}

package/dist/event-store.d.ts

@@ -0,0 +1,15 @@
+import type { HermesAgent, OfficeEvent } from "./types.js";
+export declare class OfficeEventStore {
+    private readonly agents;
+    constructor(initialAgents?: HermesAgent[]);
+    apply(event: OfficeEvent): HermesAgent[];
+    snapshot(): HermesAgent[];
+}
+export declare function sessionToAgent(session: {
+    id: string;
+    source?: string;
+    model?: string;
+    title?: string | null;
+    last_active?: number;
+    end_reason?: string | null;
+}): HermesAgent;

package/dist/event-store.js

@@ -0,0 +1,35 @@
+export class OfficeEventStore {
+    agents = new Map();
+    constructor(initialAgents = []) {
+        for (const agent of initialAgents)
+            this.agents.set(agent.id, agent);
+    }
+    apply(event) {
+        if (event.type === "snapshot") {
+            this.agents.clear();
+            for (const agent of event.agents)
+                this.agents.set(agent.id, agent);
+        }
+        if (event.type === "agent.updated") {
+            const existing = this.agents.get(event.agent.id);
+            this.agents.set(event.agent.id, { ...existing, ...event.agent });
+        }
+        if (event.type === "agent.removed")
+            this.agents.delete(event.id);
+        return this.snapshot();
+    }
+    snapshot() {
+        return [...this.agents.values()];
+    }
+}
+export function sessionToAgent(session) {
+    return {
+        id: session.id,
+        name: session.title || session.source || "Hermes session",
+        activity: session.end_reason ? "idle" : "waiting",
+        source: session.source,
+        model: session.model,
+        sessionId: session.id,
+        lastActiveAt: session.last_active ? new Date(session.last_active * 1000).toISOString() : undefined,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { HermesOffice } from "./HermesOffice.js";
+export { OfficeEventStore, sessionToAgent } from "./event-store.js";
+export { createSseEventSource } from "./event-source.js";
+export type { AgentActivity, AgentEventSource, HermesAgent, HermesRunEvent, HermesSessionSummary, OfficeEvent, OfficeTheme, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { HermesOffice } from "./HermesOffice.js";
+export { OfficeEventStore, sessionToAgent } from "./event-store.js";
+export { createSseEventSource } from "./event-source.js";

package/dist/types.d.ts

@@ -0,0 +1,45 @@
+export type AgentActivity = "idle" | "thinking" | "writing" | "reading" | "waiting" | "error";
+export type HermesAgent = {
+    id: string;
+    name: string;
+    activity: AgentActivity;
+    source?: string;
+    model?: string;
+    sessionId?: string;
+    lastActiveAt?: string;
+    x?: number;
+    y?: number;
+};
+export type OfficeEvent = {
+    type: "snapshot";
+    agents: HermesAgent[];
+} | {
+    type: "agent.updated";
+    agent: HermesAgent;
+} | {
+    type: "agent.removed";
+    id: string;
+};
+export interface AgentEventSource {
+    subscribe(onEvent: (event: OfficeEvent) => void): () => void;
+}
+export type HermesSessionSummary = {
+    id: string;
+    source?: string;
+    model?: string;
+    title?: string | null;
+    last_active?: number;
+    end_reason?: string | null;
+};
+export type HermesRunEvent = {
+    type?: string;
+    event?: string;
+    data?: unknown;
+};
+export type OfficeTheme = {
+    floor: string;
+    wall: string;
+    desk: string;
+    text: string;
+    accent: string;
+};

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@vgalletti/hermes-office",
+  "version": "0.1.0",
+  "description": "Canvas visualization library for Hermes agent activity.",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=19",
+    "react-dom": ">=19"
+  },
+  "devDependencies": {
+    "@types/node": "26.1.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "next": "^16.2.10",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "^5.7.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.lib.json",
+    "typecheck": "tsc --noEmit -p tsconfig.lib.json",
+    "dev": "next dev",
+    "demo:build": "next build",
+    "demo:start": "next start"
+  }
+}