@amalgm/chat 0.1.2 → 0.2.1

package/host/http.d.ts

@@ -0,0 +1,32 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import type { Chat } from '../dist/sessions/index.js';
+
+export interface ChatHttpHandlerOptions<Binding = unknown, RuntimeSession = unknown> {
+  readonly chat: Chat<Binding, RuntimeSession>;
+  readonly prefix?: string;
+  readonly bodyLimitBytes?: number;
+  readonly forwardEgress?: ChatAuxiliaryHandler<{
+    readonly sessionId: string;
+    readonly upstreamPath: string;
+  }>;
+  readonly forwardMcp?: ChatAuxiliaryHandler<{
+    readonly sessionId: string;
+    readonly serverName: string;
+    readonly search: string;
+  }>;
+}
+
+export type ChatAuxiliaryHandler<Input> = (
+  request: IncomingMessage,
+  response: ServerResponse,
+  input: Input,
+) => Promise<void> | void;
+
+export type ChatHttpHandler = (
+  request: IncomingMessage,
+  response: ServerResponse,
+) => Promise<boolean>;
+
+export function createChatHttpHandler<Binding = unknown, RuntimeSession = unknown>(
+  options: ChatHttpHandlerOptions<Binding, RuntimeSession>,
+): ChatHttpHandler;

package/host/http.js

@@ -0,0 +1,238 @@
+const JSON_HEADERS = Object.freeze({
+  'content-type': 'application/json; charset=utf-8',
+  'cache-control': 'no-store',
+});
+
+function object(value) {
+  return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
+}
+
+async function readJson(request, limit) {
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of request) {
+    const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+    size += buffer.length;
+    if (size > limit) throw Object.assign(new Error(`Request body exceeds ${limit} bytes`), {
+      code: 'REQUEST_TOO_LARGE',
+    });
+    chunks.push(buffer);
+  }
+  if (chunks.length === 0) return {};
+  const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    throw Object.assign(new Error('Request body must be a JSON object'), { code: 'INVALID_REQUEST' });
+  }
+  return value;
+}
+
+function statusFor(error) {
+  if (error?.code === 'SESSION_NOT_FOUND') return 404;
+  if (error?.code === 'INTERRUPT_UNSUPPORTED') return 501;
+  if (['SESSION_ALREADY_EXISTS', 'SESSION_BUSY', 'SESSION_AGENT_MISMATCH',
+    'EXECUTION_REVISION_MISMATCH'].includes(error?.code)) return 409;
+  if (error instanceof SyntaxError || String(error?.code || '').startsWith('INVALID_')
+    || error?.code === 'EXECUTION_NOT_PREPARED') return 400;
+  if (error?.code === 'REQUEST_TOO_LARGE') return 413;
+  return 500;
+}
+
+function errorBody(error) {
+  return {
+    error: {
+      code: typeof error?.code === 'string' ? error.code : 'CHAT_ERROR',
+      message: error instanceof Error ? error.message : String(error),
+    },
+  };
+}
+
+function sendJson(response, status, value) {
+  const body = JSON.stringify(value);
+  response.writeHead(status, { ...JSON_HEADERS, 'content-length': Buffer.byteLength(body) });
+  response.end(body);
+}
+
+function writeSse(response, event, value, id) {
+  if (response.destroyed) return false;
+  if (id !== undefined) response.write(`id: ${id}\n`);
+  response.write(`event: ${event}\n`);
+  response.write(`data: ${JSON.stringify(value)}\n\n`);
+  return true;
+}
+
+function updateSequence(update) {
+  const value = update?._meta?.amalgm?.sequence;
+  return Number.isFinite(value) ? Number(value) : undefined;
+}
+
+function listOptions(url) {
+  const number = (name) => {
+    const value = url.searchParams.get(name);
+    return value === null ? undefined : Number(value);
+  };
+  return {
+    agentInstallationId: url.searchParams.get('agentInstallationId') || undefined,
+    origin: url.searchParams.get('origin') || undefined,
+    originId: url.searchParams.get('originId') || undefined,
+    includeArchived: url.searchParams.get('includeArchived') === 'true',
+    offset: number('offset'),
+    limit: number('limit'),
+  };
+}
+
+async function streamTurn(response, updates, completion) {
+  response.writeHead(200, {
+    'content-type': 'text/event-stream; charset=utf-8',
+    'cache-control': 'no-store',
+    connection: 'keep-alive',
+  });
+  response.flushHeaders?.();
+  try {
+    for await (const update of updates) {
+      if (!writeSse(response, 'update', update, updateSequence(update))) return;
+    }
+    const turn = await (typeof completion === 'function' ? completion() : completion);
+    writeSse(response, 'complete', turn);
+  } catch (error) {
+    writeSse(response, 'error', errorBody(error).error);
+  } finally {
+    if (!response.destroyed) response.end();
+  }
+}
+
+/** Node HTTP adapter over the public Chat capability. */
+export function createChatHttpHandler(options) {
+  if (!options?.chat) throw new TypeError('createChatHttpHandler requires chat');
+  const chat = options.chat;
+  const prefix = String(options.prefix || '/chat').replace(/\/$/, '');
+  const bodyLimit = options.bodyLimitBytes || 2_000_000;
+
+  return async function handleChatHttp(request, response) {
+    const url = new URL(request.url || '/', 'http://localhost');
+    if (url.pathname !== prefix && !url.pathname.startsWith(`${prefix}/`)) return false;
+    const path = url.pathname.slice(prefix.length).split('/').filter(Boolean).map(decodeURIComponent);
+    const method = request.method || 'GET';
+    try {
+      if (path[0] === 'egress' && path[1]) {
+        if (typeof options.forwardEgress !== 'function') {
+          sendJson(response, 501, errorBody(Object.assign(new Error('Platform egress is not configured'), {
+            code: 'EGRESS_NOT_CONFIGURED',
+          })));
+          return true;
+        }
+        await options.forwardEgress(request, response, {
+          sessionId: path[1],
+          upstreamPath: `/${path.slice(2).map(encodeURIComponent).join('/')}${url.search}`,
+        });
+        return true;
+      }
+      if (path[0] === 'mcp' && path[1] && path[2]) {
+        if (typeof options.forwardMcp !== 'function') {
+          sendJson(response, 501, errorBody(Object.assign(new Error('MCP relay is not configured'), {
+            code: 'MCP_RELAY_NOT_CONFIGURED',
+          })));
+          return true;
+        }
+        await options.forwardMcp(request, response, {
+          sessionId: path[1],
+          serverName: path[2],
+          search: url.search,
+        });
+        return true;
+      }
+      if (method === 'POST' && path[0] === 'executions' && path.length === 1) {
+        const body = await readJson(request, bodyLimit);
+        const execution = await chat.prepareExecution(body.id, body.execution);
+        sendJson(response, 201, { execution });
+        return true;
+      }
+      if (path[0] !== 'conversations') {
+        sendJson(response, 404, errorBody(Object.assign(new Error('Route not found'), { code: 'NOT_FOUND' })));
+        return true;
+      }
+      if (method === 'GET' && path.length === 1) {
+        sendJson(response, 200, { conversations: await chat.listConversations(listOptions(url)) });
+        return true;
+      }
+      if (method === 'POST' && path.length === 1) {
+        const body = await readJson(request, bodyLimit);
+        const session = await chat.startSession({
+          sessionId: body.conversationId,
+          execution: body.execution,
+          title: body.title,
+          origin: body.origin,
+          originId: body.originId,
+          metadata: object(body.metadata),
+        });
+        sendJson(response, 201, { conversation: await session.inspect() });
+        return true;
+      }
+      const conversationId = path[1];
+      if (!conversationId) throw Object.assign(new Error('conversation id is required'), { code: 'INVALID_REQUEST' });
+      if (method === 'POST' && path[2] === 'resume' && path.length === 3) {
+        const body = await readJson(request, bodyLimit);
+        const result = body.execution
+          ? { session: await chat.resumeSession({ sessionId: conversationId, execution: body.execution }) }
+          : await chat.resumeStoredSession(conversationId);
+        sendJson(response, 200, { conversation: await result.session.inspect(), execution: result.execution });
+        return true;
+      }
+      if (method === 'POST' && path[2] === 'turns' && path.length === 3) {
+        const body = await readJson(request, bodyLimit);
+        const stream = await chat.send(conversationId, {
+          execution: body.execution,
+          prompt: body.prompt,
+          clientTurnId: body.clientTurnId,
+          userMessageId: body.userMessageId,
+          assistantMessageId: body.assistantMessageId,
+        });
+        await streamTurn(response, stream, stream.completion);
+        return true;
+      }
+      if (method === 'GET' && path[2] === 'turns' && path[3] && path[4] === 'events') {
+        const after = Number(url.searchParams.get('afterSequence') || request.headers['last-event-id'] || 0);
+        const updates = chat.reconnectTurn(conversationId, path[3], after);
+        await streamTurn(response, updates, async () => (await chat.replayTurn(
+          conversationId,
+          path[3],
+          after,
+        )).turn);
+        return true;
+      }
+      if (method === 'POST' && path[2] === 'interrupt' && path.length === 3) {
+        sendJson(response, 200, await chat.interruptSession(conversationId));
+        return true;
+      }
+      if (method === 'GET' && path[2] === 'active' && path.length === 3) {
+        sendJson(response, 200, { turn: await chat.activeTurn(conversationId) });
+        return true;
+      }
+      if (method === 'GET' && path.length === 2) {
+        sendJson(response, 200, {
+          conversation: await chat.inspectSession(conversationId),
+          messages: await chat.listMessages(conversationId),
+          latestTurn: await chat.latestTurn(conversationId),
+        });
+        return true;
+      }
+      if (method === 'PATCH' && path.length === 2) {
+        const body = await readJson(request, bodyLimit);
+        const conversation = body.newMessages === false
+          ? await chat.markSeen(conversationId)
+          : await chat.updateTitle(conversationId, body.title);
+        sendJson(response, 200, { conversation });
+        return true;
+      }
+      if (method === 'DELETE' && path.length === 2) {
+        sendJson(response, 200, { conversation: await chat.archiveSession(conversationId) });
+        return true;
+      }
+      sendJson(response, 404, errorBody(Object.assign(new Error('Route not found'), { code: 'NOT_FOUND' })));
+      return true;
+    } catch (error) {
+      if (!response.headersSent) sendJson(response, statusFor(error), errorBody(error));
+      else if (!response.destroyed) response.end();
+      return true;
+    }
+  };
+}

package/host/index.d.ts

@@ -0,0 +1,84 @@
+import type {
+  Chat,
+  ChatRuntimePort,
+  ClockIsoPort,
+  RandomUuidPort,
+  Sha256HexPort,
+} from '../dist/index.js';
+import type { ConversationStorePort, ConversationTurn } from '../dist/conversations/index.js';
+import type { ChatHttpHandler } from './http.js';
+
+export interface PlatformCredentialBroker {
+  authorize(request: Readonly<{
+    audience: 'amalgm-api-proxy';
+    scopes: readonly string[];
+    method: string;
+    url: string;
+  }>): Promise<Readonly<{
+    accessToken: string;
+    authorization: string;
+    dpop: string;
+  }>>;
+  invalidate(credential: Readonly<{ accessToken: string }>): void;
+}
+
+export interface CreateChatHostOptions<Binding = unknown, RuntimeSession = unknown> {
+  readonly ownerUserId: string;
+  readonly databasePath?: string;
+  readonly conversations?: ConversationStorePort;
+  readonly runtime?: ChatRuntimePort<Binding, RuntimeSession>;
+  readonly native?: Readonly<Record<string, unknown>> & {
+    readonly credentialBroker?: PlatformCredentialBroker;
+  };
+  readonly uuid?: RandomUuidPort;
+  readonly clockIso?: ClockIsoPort;
+  readonly sha256Hex?: Sha256HexPort;
+  readonly subscriberBufferSize?: number;
+  readonly journalBatch?: false | {
+    readonly maxUpdates: number;
+    readonly maxDelayMs: number;
+    readonly wait: (milliseconds: number) => Promise<void>;
+  };
+}
+
+export interface ComposedChatHost<Binding = unknown, RuntimeSession = unknown> {
+  readonly chat: Chat<Binding, RuntimeSession>;
+  readonly runtime: ChatRuntimePort<Binding, RuntimeSession>;
+  readonly conversations: ConversationStorePort;
+  readonly recoveredTurns: readonly ConversationTurn[];
+  readonly handleHttp: ChatHttpHandler;
+  close(): Promise<void>;
+}
+
+export function createChatHost<Binding = unknown, RuntimeSession = unknown>(
+  options: CreateChatHostOptions<Binding, RuntimeSession>,
+): Promise<ComposedChatHost<Binding, RuntimeSession>>;
+
+export { createChatHttpHandler } from './http.js';
+export type { ChatHttpHandler, ChatHttpHandlerOptions } from './http.js';
+
+export class NativeChatRuntime implements ChatRuntimePort<unknown, unknown> {
+  constructor(options?: Readonly<Record<string, unknown>>);
+  prepareExecution(contract: import('../dist/execution/index.js').ExecutionContract): Promise<unknown>;
+  startSession(request: import('../dist/sessions/index.js').RuntimeStartRequest<unknown>): Promise<unknown>;
+  resumeSession(request: import('../dist/sessions/index.js').RuntimeResumeRequest<unknown>): Promise<unknown>;
+  prompt(request: import('../dist/sessions/index.js').RuntimePromptRequest<unknown, unknown>): AsyncIterable<import('@agentclientprotocol/sdk').SessionUpdate>;
+  interruptTurn(request: import('../dist/sessions/index.js').RuntimeInterruptRequest<unknown, unknown>): Promise<void>;
+  checkpointSession(request: { readonly session: unknown }): unknown;
+  closeSession(sessionId: string, session: unknown): Promise<void>;
+}
+
+export class NativeExecutionPreparer {
+  constructor(options?: Readonly<Record<string, unknown>>);
+  prepare(contract: import('../dist/execution/index.js').ExecutionContract): Promise<unknown>;
+}
+
+export class InvalidPreparedAuthError extends Error {
+  readonly code: 'INVALID_PREPARED_AUTH';
+}
+
+export {
+  SqliteConversationStore,
+  SqliteConversationStoreError,
+  createSqliteJournalBatchPolicy,
+} from './sqlite/index.js';

package/host/index.js

@@ -0,0 +1,59 @@
+import { createHash, randomUUID } from 'node:crypto';
+
+import { Chat } from '../dist/sessions/index.js';
+import { NativeChatRuntime } from './native-runtime.js';
+import { createChatHttpHandler } from './http.js';
+import {
+  SqliteConversationStore,
+  createSqliteJournalBatchPolicy,
+} from './sqlite/index.js';
+
+/** Compose the public Chat capability with Node host effects. */
+export async function createChatHost(options) {
+  if (!options || typeof options !== 'object') {
+    throw new TypeError('createChatHost options are required');
+  }
+  const conversations = options.conversations || new SqliteConversationStore({
+    databasePath: options.databasePath,
+  });
+  const runtime = options.runtime || new NativeChatRuntime(options.native || {});
+  const chat = new Chat({
+    runtime,
+    ownerUserId: options.ownerUserId,
+    conversations,
+    uuid: options.uuid || randomUUID,
+    clockIso: options.clockIso || (() => new Date().toISOString()),
+    sha256Hex: options.sha256Hex || ((value) => createHash('sha256').update(value).digest('hex')),
+    subscriberBufferSize: options.subscriberBufferSize,
+    journalBatch: options.journalBatch === false
+      ? undefined
+      : options.journalBatch || createSqliteJournalBatchPolicy(),
+  });
+  const recoveredTurns = await chat.recoverInterruptedTurns();
+  const handleHttp = createChatHttpHandler({
+    chat,
+    ...(typeof runtime.forwardEgress === 'function'
+      ? { forwardEgress: runtime.forwardEgress.bind(runtime) }
+      : {}),
+    ...(typeof runtime.forwardMcp === 'function'
+      ? { forwardMcp: runtime.forwardMcp.bind(runtime) }
+      : {}),
+  });
+  return Object.freeze({
+    chat,
+    runtime,
+    conversations,
+    recoveredTurns,
+    handleHttp,
+    close: () => chat.close(),
+  });
+}
+
+export { NativeChatRuntime } from './native-runtime.js';
+export { createChatHttpHandler } from './http.js';
+export { NativeExecutionPreparer, InvalidPreparedAuthError } from './native-contract.js';
+export {
+  SqliteConversationStore,
+  SqliteConversationStoreError,
+  createSqliteJournalBatchPolicy,
+} from './sqlite/index.js';

package/host/lib/runtime-paths.js

@@ -0,0 +1,44 @@
+/**
+ * Small documented port of engine `runtime/scripts/lib/runtime-paths.js`
+ * (other subsystem — see HOST CONVENTIONS). Only the subset the host layer
+ * consumes is ported: `amalgmDir`, `runtimeLabel`, `runtimeStateDir`.
+ *
+ * Engine default for `amalgmDir()` when `AMALGM_DIR` is unset: resolve the
+ * Amalgm home via `amalgm-mcp/lib/layout.resolveAmalgmHome` and pick the
+ * per-user directory (`<home>/users/<scope>`) via user-scope discovery
+ * (AMALGM_RUNTIME_USER_ID / computer.json / auth.json / layout user entries).
+ * That discovery lives in amalgm-mcp (another repo's material), so this host
+ * port simplifies to `~/.amalgm` — orchestrators set `AMALGM_DIR` explicitly
+ * (engine: entrypoint.sh / electron/main.ts), which is the path every
+ * production deployment takes.
+ */
+
+import os from 'node:os';
+import path from 'node:path';
+
+/** Engine `normalizeRuntimeLabel` (`lib/runtime-paths.js:7-12`), byte-faithful. */
+function normalizeRuntimeLabel(value) {
+  const raw = String(value || '').trim().toLowerCase();
+  if (['preview', 'canary', 'native-chat', 'staging'].includes(raw)) return 'preview';
+  if (['local', 'dev', 'development'].includes(raw)) return 'local';
+  return 'main';
+}
+
+export function amalgmDir() {
+  if (process.env.AMALGM_DIR) return process.env.AMALGM_DIR;
+  // Engine default: layout.resolveUserDir(layout.resolveAmalgmHome(env), scope).
+  return path.join(os.homedir(), '.amalgm');
+}
+
+/** Engine `runtimeLabel` (`lib/runtime-paths.js:77-79`). */
+export function runtimeLabel() {
+  return normalizeRuntimeLabel(process.env.AMALGM_RUNTIME_LABEL || process.env.AMALGM_BRANCH);
+}
+
+/** Engine `runtimeStateDir` (`lib/runtime-paths.js:81-86`). */
+export function runtimeStateDir() {
+  return (
+    process.env.AMALGM_RUNTIME_STATE_DIR
+    || path.join(amalgmDir(), 'runtimes', runtimeLabel())
+  );
+}