@greppleai/grip 0.0.0-stage → 0.1.3

package/examples/remote-session-server/README.md

@@ -0,0 +1,71 @@
+# Remote session storage server
+
+Example Hono server for Grip remote sessions. It stores each session as a JSONL file for easy inspection and uses a static bearer token.
+
+This server is for protocol development only. It does not provide atomic publication, process-safe concurrency, tenant isolation, TLS, or power-loss durability and must not be used to certify a production remote session service. The client supports services with optional ETags, but a service that omits ETags has only a single-client consistency assumption.
+
+## Run
+
+```bash
+GRIP_REMOTE_SESSION_TOKEN=dev-token \
+GRIP_REMOTE_SESSION_DIR=/tmp/grip-remote-sessions \
+npx tsx packages/coding-agent/examples/remote-session-server/server.ts
+```
+
+The server listens on `http://localhost:8787` by default. Override with `PORT`. Requests and session operations are logged to stdout.
+
+## Use from the Grip CLI
+
+From the repo root:
+
+```bash
+GRIP_REMOTE_SESSION_BASE_URL=http://localhost:8787 \
+GRIP_REMOTE_SESSION_TOKEN=dev-token \
+./grip-test.sh
+```
+
+Equivalent flags:
+
+```bash
+./grip-test.sh --remote-session-base-url http://localhost:8787 --remote-session-token dev-token
+```
+
+Optional project id:
+
+```bash
+GRIP_REMOTE_PROJECT_ID=my-project \
+GRIP_REMOTE_SESSION_BASE_URL=http://localhost:8787 \
+GRIP_REMOTE_SESSION_TOKEN=dev-token \
+./grip-test.sh
+```
+
+## Use from the SDK
+
+```ts
+import { GripAgent, RemoteSessionManager } from "@greppleai/grip";
+
+const sessionManager = new RemoteSessionManager({
+  baseUrl: "http://localhost:8787",
+  token: "dev-token",
+  cwd: process.cwd(),
+});
+
+const grip = await GripAgent.create({ sessionManager });
+const session = await grip.createAgentSession();
+await session.prompt("hello from a remote session");
+await session.waitForIdle();
+await grip.dispose();
+```
+
+Sessions are stored as `<session-id>.jsonl` under `GRIP_REMOTE_SESSION_DIR`.
+
+## API covered
+
+- `POST /v1/sessions`
+- `GET /v1/sessions`
+- `GET /v1/sessions/recent`
+- `GET /v1/sessions/:id`
+- `POST /v1/sessions/:id/entries`
+- `PUT /v1/sessions/:id/snapshot`
+- `POST /v1/sessions/:id/fork`
+- `POST /v1/sessions/import-jsonl`

package/examples/remote-session-server/server.ts

@@ -0,0 +1,353 @@
+import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
+import { mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import {
+	type AppendRemoteSessionEntriesRequest,
+	type CreateRemoteSessionRequest,
+	CURRENT_SESSION_VERSION,
+	type FileEntry,
+	type ForkRemoteSessionRequest,
+	type ImportRemoteSessionJsonlRequest,
+	type ReplaceRemoteSessionSnapshotRequest,
+	type SessionEntry,
+	type SessionHeader,
+	type SessionInfo,
+} from "@greppleai/grip";
+import type { TextContent } from "@greppleai/grip-ai";
+import { serve } from "@hono/node-server";
+import { Hono } from "hono";
+
+// grip-ignore noNearIdenticalDataStructures: The server always emits an ETag, while the client snapshot contract keeps it optional to tolerate compatible remote implementations.
+interface RemoteSessionSnapshot {
+	reference: string;
+	id: string;
+	version?: number;
+	entries: FileEntry[];
+	etag: string;
+}
+
+const port = Number.parseInt(process.env.PORT ?? "8787", 10);
+const token = process.env.GRIP_REMOTE_SESSION_TOKEN ?? "dev-token";
+const dataDir = process.env.GRIP_REMOTE_SESSION_DIR ?? join(process.cwd(), ".grip-remote-sessions");
+const app = new Hono();
+
+function log(message: string, details?: Record<string, unknown>): void {
+	const suffix = details ? ` ${JSON.stringify(details)}` : "";
+	console.log(`[${new Date().toISOString()}] ${message}${suffix}`);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isSessionId(value: string): boolean {
+	return /^[A-Za-z0-9._-]+$/.test(value);
+}
+
+function stripRemotePrefix(reference: string): string {
+	return reference.startsWith("remote:") ? reference.slice("remote:".length) : reference;
+}
+
+function assertSessionId(value: string): string {
+	const id = stripRemotePrefix(value);
+	if (!isSessionId(id)) {
+		throw new Error(`Invalid session id: ${value}`);
+	}
+	return id;
+}
+
+function createSessionId(): string {
+	return randomUUID();
+}
+
+function sessionPath(sessionId: string): string {
+	return join(dataDir, `${assertSessionId(sessionId)}.jsonl`);
+}
+
+function referenceFor(sessionId: string): string {
+	return `remote:${sessionId}`;
+}
+
+function etagFor(entries: FileEntry[]): string {
+	return createHash("sha256")
+		.update(entries.map((entry) => JSON.stringify(entry)).join("\n"))
+		.digest("hex");
+}
+
+function writeJsonl(entries: FileEntry[]): string {
+	return `${entries.map((entry) => JSON.stringify(entry)).join("\n")}\n`;
+}
+
+function parseJsonl(content: string): FileEntry[] {
+	const entries: FileEntry[] = [];
+	for (const line of content.split("\n")) {
+		if (!line.trim()) continue;
+		entries.push(JSON.parse(line) as FileEntry);
+	}
+	return entries;
+}
+
+async function loadEntries(sessionId: string): Promise<FileEntry[]> {
+	return parseJsonl(await readFile(sessionPath(sessionId), "utf8"));
+}
+
+async function saveEntries(sessionId: string, entries: FileEntry[]): Promise<void> {
+	await mkdir(dataDir, { recursive: true });
+	await writeFile(sessionPath(sessionId), writeJsonl(entries), "utf8");
+}
+
+function snapshotFor(sessionId: string, entries: FileEntry[]): RemoteSessionSnapshot {
+	const header = entries[0];
+	return {
+		reference: referenceFor(sessionId),
+		id: sessionId,
+		version: header?.type === "session" ? header.version : undefined,
+		entries,
+		etag: etagFor(entries),
+	};
+}
+
+function validateBaseEtag(entries: FileEntry[], baseEtag: string | undefined): boolean {
+	return baseEtag === undefined || baseEtag === etagFor(entries);
+}
+
+function makeHeader(id: string, cwd: string, parentSession?: string): SessionHeader {
+	return {
+		type: "session",
+		version: CURRENT_SESSION_VERSION,
+		id,
+		timestamp: new Date().toISOString(),
+		cwd,
+		parentSession,
+	};
+}
+
+function getBranch(entries: FileEntry[], leafId: string | undefined): SessionEntry[] {
+	const sessionEntries = entries.filter((entry): entry is SessionEntry => entry.type !== "session");
+	if (leafId === undefined) {
+		return sessionEntries.filter((entry) => entry.type !== "label");
+	}
+
+	const byId = new Map(sessionEntries.map((entry) => [entry.id, entry]));
+	const path: SessionEntry[] = [];
+	let current: string | null | undefined = leafId;
+	while (current) {
+		const entry = byId.get(current);
+		if (!entry) {
+			throw new Error(`Entry ${leafId} not found`);
+		}
+		path.unshift(entry);
+		current = entry.parentId;
+	}
+	return path.filter((entry) => entry.type !== "label");
+}
+
+function forkEntries(sourceEntries: FileEntry[], header: SessionHeader, leafId: string | undefined): FileEntry[] {
+	const path = getBranch(sourceEntries, leafId);
+	const pathIds = new Set(path.map((entry) => entry.id));
+	const labelEntries = sourceEntries.filter((entry) => entry.type === "label" && pathIds.has(entry.targetId));
+	return [header, ...structuredClone(path), ...structuredClone(labelEntries)];
+}
+
+interface MessageContentEnvelope {
+	role?: string;
+	content?: unknown;
+}
+
+function isMessageWithContent(value: unknown): value is MessageContentEnvelope {
+	return isRecord(value) && "content" in value;
+}
+
+function extractText(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (!Array.isArray(value)) return "";
+	return value
+		.filter((part): part is TextContent => isRecord(part) && part.type === "text" && typeof part.text === "string")
+		.map((part) => part.text)
+		.join(" ");
+}
+
+type SearchableSessionMessageRole = "user" | "assistant";
+
+interface SearchableSessionMessage {
+	role: SearchableSessionMessageRole;
+	text: string;
+}
+
+interface SessionEntrySummary {
+	name: string | undefined;
+	messageCount: number;
+	firstMessage: string;
+	allMessagesText: string;
+}
+
+function extractSearchableSessionMessage(entry: FileEntry): SearchableSessionMessage | undefined {
+	if (entry.type !== "message") return undefined;
+	const message = entry.message;
+	if (!isMessageWithContent(message)) return undefined;
+	if (message.role !== "user" && message.role !== "assistant") return undefined;
+	const text = extractText(message.content);
+	return text ? { role: message.role, text } : undefined;
+}
+
+function summarizeSessionEntries(entries: FileEntry[]): SessionEntrySummary {
+	let name: string | undefined;
+	let messageCount = 0;
+	let firstMessage = "";
+	const allMessages: string[] = [];
+	for (const entry of entries) {
+		if (entry.type === "session_info") name = entry.name?.trim() || undefined;
+		if (entry.type !== "message") continue;
+		messageCount++;
+		const message = extractSearchableSessionMessage(entry);
+		if (!message) continue;
+		allMessages.push(message.text);
+		if (!firstMessage && message.role === "user") firstMessage = message.text;
+	}
+	return { name, messageCount, firstMessage, allMessagesText: allMessages.join(" ") };
+}
+function sessionInfo(sessionId: string, entries: FileEntry[], modified: Date): SessionInfo | null {
+	const header = entries[0];
+	if (header?.type !== "session") return null;
+
+	const summary = summarizeSessionEntries(entries);
+
+	return {
+		reference: referenceFor(sessionId),
+		path: referenceFor(sessionId),
+		id: sessionId,
+		cwd: header.cwd,
+		name: summary.name,
+		parentSessionPath: header.parentSession,
+		created: new Date(header.timestamp),
+		modified,
+		messageCount: summary.messageCount,
+		firstMessage: summary.firstMessage || "(no messages)",
+		allMessagesText: summary.allMessagesText,
+	};
+}
+
+function authorized(authHeader: string | undefined): boolean {
+	const prefix = "Bearer ";
+	if (!authHeader?.startsWith(prefix)) return false;
+	const received = Buffer.from(authHeader.slice(prefix.length));
+	const expected = Buffer.from(token);
+	return received.length === expected.length && timingSafeEqual(received, expected);
+}
+
+app.use("/v1/*", async (ctx, next) => {
+	const started = Date.now();
+	const method = ctx.req.method;
+	const path = new URL(ctx.req.url).pathname;
+	log("request", { method, path });
+
+	if (!authorized(ctx.req.header("Authorization"))) {
+		log("response", { method, path, status: 401, durationMs: Date.now() - started });
+		return ctx.text("Unauthorized", 401);
+	}
+
+	await next();
+	log("response", { method, path, status: ctx.res.status, durationMs: Date.now() - started });
+});
+
+app.get("/health", (ctx) => ctx.json({ ok: true, dataDir }));
+
+app.post("/v1/sessions", async (ctx) => {
+	const body = (await ctx.req.json()) as CreateRemoteSessionRequest;
+	const id = assertSessionId(body.id ?? createSessionId());
+	const entries: FileEntry[] = [makeHeader(id, body.cwd, body.parentSession)];
+	log("create session", { id, cwd: body.cwd, parentSession: body.parentSession, projectId: body.projectId });
+	await saveEntries(id, entries);
+	return ctx.json(snapshotFor(id, entries));
+});
+
+app.get("/v1/sessions", async (ctx) => {
+	await mkdir(dataDir, { recursive: true });
+	const files = (await readdir(dataDir)).filter((file) => file.endsWith(".jsonl"));
+	const sessions: SessionInfo[] = [];
+	for (const file of files) {
+		const id = file.slice(0, -".jsonl".length);
+		const path = sessionPath(id);
+		const entries = parseJsonl(await readFile(path, "utf8"));
+		const info = sessionInfo(id, entries, (await stat(path)).mtime);
+		if (info) sessions.push(info);
+	}
+	log("list sessions", { count: sessions.length });
+	return ctx.json({ sessions: sessions.sort((a, b) => b.modified.getTime() - a.modified.getTime()) });
+});
+
+app.get("/v1/sessions/recent", async (ctx) => {
+	await mkdir(dataDir, { recursive: true });
+	const files = (await readdir(dataDir)).filter((file) => file.endsWith(".jsonl"));
+	let recent: { id: string; modified: Date } | undefined;
+	for (const file of files) {
+		const id = file.slice(0, -".jsonl".length);
+		const modified = (await stat(sessionPath(id))).mtime;
+		if (!recent || modified > recent.modified) {
+			recent = { id, modified };
+		}
+	}
+	if (!recent) return ctx.text("No sessions", 404);
+	const entries = await loadEntries(recent.id);
+	log("recent session", { id: recent.id, entries: entries.length });
+	return ctx.json(snapshotFor(recent.id, entries));
+});
+
+app.get("/v1/sessions/:id", async (ctx) => {
+	const id = assertSessionId(ctx.req.param("id"));
+	const entries = await loadEntries(id);
+	log("open session", { id, entries: entries.length });
+	return ctx.json(snapshotFor(id, entries));
+});
+
+app.post("/v1/sessions/:id/entries", async (ctx) => {
+	const id = assertSessionId(ctx.req.param("id"));
+	const body = (await ctx.req.json()) as AppendRemoteSessionEntriesRequest;
+	const entries = await loadEntries(id);
+	if (!validateBaseEtag(entries, body.baseEtag)) return ctx.text("ETag mismatch", 409);
+	const nextEntries = [...entries, ...body.entries];
+	log("append entries", {
+		id,
+		entries: body.entries.length,
+		totalEntries: nextEntries.length,
+		baseEtag: body.baseEtag,
+	});
+	await saveEntries(id, nextEntries);
+	return ctx.json({ accepted: body.entries.length, etag: etagFor(nextEntries) });
+});
+
+app.put("/v1/sessions/:id/snapshot", async (ctx) => {
+	const id = assertSessionId(ctx.req.param("id"));
+	const body = (await ctx.req.json()) as ReplaceRemoteSessionSnapshotRequest;
+	const entries = await loadEntries(id);
+	if (!validateBaseEtag(entries, body.baseEtag)) return ctx.text("ETag mismatch", 409);
+	log("replace snapshot", { id, entries: body.entries.length, baseEtag: body.baseEtag });
+	await saveEntries(id, body.entries);
+	return ctx.json({ etag: etagFor(body.entries) });
+});
+
+app.post("/v1/sessions/:id/fork", async (ctx) => {
+	const sourceId = assertSessionId(ctx.req.param("id"));
+	const body = (await ctx.req.json()) as ForkRemoteSessionRequest;
+	const forkId = createSessionId();
+	const sourceEntries = await loadEntries(sourceId);
+	const entries = forkEntries(sourceEntries, makeHeader(forkId, body.cwd, referenceFor(sourceId)), body.leafId);
+	log("fork session", { sourceId, forkId, leafId: body.leafId, entries: entries.length, projectId: body.projectId });
+	await saveEntries(forkId, entries);
+	return ctx.json(snapshotFor(forkId, entries));
+});
+
+app.post("/v1/sessions/import-jsonl", async (ctx) => {
+	const body = (await ctx.req.json()) as ImportRemoteSessionJsonlRequest;
+	const id = assertSessionId(body.entries[0]?.type === "session" ? body.entries[0].id : createSessionId());
+	const entries = body.entries[0]?.type === "session" ? body.entries : [makeHeader(id, body.cwd), ...body.entries];
+	log("import jsonl", { id, sourceName: body.sourceName, entries: entries.length, projectId: body.projectId });
+	await saveEntries(id, entries);
+	return ctx.json(snapshotFor(id, entries));
+});
+
+serve({ fetch: app.fetch, port }, (info) => {
+	console.log(`Remote session server listening on http://localhost:${info.port}`);
+	console.log(`Data directory: ${dataDir}`);
+	console.log(`Bearer token: ${token}`);
+});