@aion0/forge 0.6.3 → 0.8.1

package/lib/chat/memory-store.ts

@@ -0,0 +1,87 @@
+/**
+ * MemoryStore — common surface for chat's long-term memory.
+ *
+ * Two implementations:
+ *  - TemperClient (lib/chat/temper.ts): HTTP-backed, with semantic +
+ *    graph search via Graphiti.
+ *  - LocalMemoryStore (lib/chat/local-memory.ts): SQLite-backed
+ *    fallback when Temper isn't configured. Same block API; search is
+ *    keyword LIKE over stored block values + episode content.
+ *
+ * The factory `getMemoryStore()` picks one based on settings:
+ *   temperUrl + temperKey present → Temper; otherwise → Local.
+ *
+ * Both report `enabled = true` once they have somewhere to read/write,
+ * so the chat loop registers the memory_* tools either way.
+ */
+
+import { loadSettings } from '../settings';
+import { TemperClient } from './temper';
+import { LocalMemoryStore } from './local-memory';
+import type { EpisodeInput, MemoryBlock, SearchHit } from './temper';
+
+export type { EpisodeInput, MemoryBlock, SearchHit } from './temper';
+
+export interface MemoryStore {
+  readonly enabled: boolean;
+  readonly currentNamespace: string;
+  readonly kind: 'temper' | 'local';
+
+  search(query: string, limit?: number): Promise<SearchHit[]>;
+  writeEpisode(ep: EpisodeInput, asyncExtract?: boolean): Promise<boolean>;
+  listBlocks(opts?: { pinned?: boolean; scope?: 'own' | 'global' | 'both' }): Promise<MemoryBlock[]>;
+  getBlock(key: string, scope?: 'own' | 'global'): Promise<MemoryBlock | null>;
+  putBlock(
+    key: string,
+    value: unknown,
+    extras?: { pinned?: boolean; priority?: number; description?: string; scope?: 'own' | 'global' },
+  ): Promise<boolean>;
+  ping(): Promise<{ ok: boolean; message: string; pinned: number }>;
+}
+
+/**
+ * Pick the active memory backend.
+ *
+ * Resolution order:
+ *   - settings.memoryBackend === 'local'  → always LocalMemoryStore.
+ *   - settings.memoryBackend === 'temper' → always TemperClient (even if
+ *     credentials are missing — caller will see `enabled = false`).
+ *   - 'auto' (default): Temper if both URL+key are set, else Local.
+ *
+ * Callers should NOT cache the result across settings edits — the
+ * picker is cheap.
+ */
+export function getMemoryStore(): MemoryStore {
+  const s = loadSettings();
+  const url = (s.temperUrl || '').trim();
+  const key = (s.temperKey || '').trim();
+  const mode = s.memoryBackend || 'auto';
+
+  if (mode === 'local') return new LocalMemoryStore();
+  if (mode === 'temper') {
+    return makeTemperWrapper(new TemperClient(url, key, s.temperNamespace || ''));
+  }
+  // auto
+  if (url && key) {
+    return makeTemperWrapper(new TemperClient(url, key, s.temperNamespace || ''));
+  }
+  return new LocalMemoryStore();
+}
+
+function makeTemperWrapper(c: TemperClient): MemoryStore {
+  return {
+    kind: 'temper',
+    get enabled() {
+      return c.enabled;
+    },
+    get currentNamespace() {
+      return c.currentNamespace;
+    },
+    search: (q, n) => c.search(q, n),
+    writeEpisode: (ep, a) => c.writeEpisode(ep, a),
+    listBlocks: (opts) => c.listBlocks(opts ?? {}),
+    getBlock: (k, scope) => c.getBlock(k, scope),
+    putBlock: (k, v, extras) => c.putBlock(k, v, extras),
+    ping: () => c.ping(),
+  };
+}

package/lib/chat/memory-tools.ts

@@ -0,0 +1,157 @@
+/**
+ * Memory tools exposed to the LLM by the chat backend.
+ *
+ * Registered whenever a MemoryStore is enabled — that's always true
+ * now: Temper if configured, otherwise the SQLite-backed
+ * LocalMemoryStore. The tool schemas and names are identical across
+ * backends; only the descriptions stay accurate (e.g. `memory_search`
+ * is keyword on local, semantic on Temper).
+ *
+ * Tool naming uses `memory_*` (no plugin prefix) so they look like
+ * first-class builtins next to get_current_time.
+ */
+
+import type { BuiltinToolDef } from './tool-dispatcher';
+import type { MemoryStore } from './memory-store';
+
+export type MemoryToolHandler = (input: unknown) => Promise<string>;
+
+export interface MemoryTool {
+  def: BuiltinToolDef;
+  handle: MemoryToolHandler;
+}
+
+export function buildMemoryTools(store: MemoryStore): MemoryTool[] {
+  if (!store.enabled) return [];
+  const isLocal = store.kind === 'local';
+  const searchDescription = isLocal
+    ? 'Keyword search over locally-stored memory blocks and episodes (case-insensitive LIKE). Use for finding past notes / events you wrote earlier. For first-person identity/preferences prefer memory_get_block / memory_list_blocks.'
+    : 'Semantic + graph search over Temper episodes (Graphiti). Use for NAMED third-party facts ("what did Alice say about X", "what was decided on the migration"). DO NOT use for first-person questions — pronouns are filtered and you will get 0 hits. For first-person, use memory_get_block / memory_list_blocks.';
+  const episodeDescription = isLocal
+    ? 'Append a short event-shaped fact to the local memory log (one row per call). Searchable via memory_search keyword match. Use for "Alice prefers Postgres", "user decided to ship X on May 20".'
+    : 'Write an event-shaped fact to long-term memory (a Temper episode). Use for "Alice prefers Postgres", "user decided to ship X on May 20", external-world facts with subject/object structure. Extraction runs async. ONE discrete fact per call — do NOT dump transcripts.';
+  return [
+    {
+      def: {
+        name: 'memory_get_block',
+        description:
+          'Read ONE memory block by key. Use this for first-person queries ("my name", "what do you call me", "my preferences"). Returns the JSON value or "(not found)".',
+        input_schema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Block key, e.g. forge_user_name / preferences.theme / persona.nickname' },
+            scope: { type: 'string', enum: ['own', 'global'], description: 'Default: own (falls back to global server-side).' },
+          },
+          required: ['key'],
+        },
+      },
+      handle: async (input) => {
+        const { key, scope } = input as { key: string; scope?: 'own' | 'global' };
+        const b = await store.getBlock(key, scope ?? 'own');
+        if (!b) return '(not found)';
+        return typeof b.value === 'string' ? b.value : JSON.stringify(b.value);
+      },
+    },
+    {
+      def: {
+        name: 'memory_list_blocks',
+        description:
+          'List memory block keys. Use when the user asks "what do you know about me" / "what have you remembered" or you need to discover what is stored. Returns key + short value preview.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            pinned_only: { type: 'boolean', description: 'If true, only pinned (auto-injected) blocks. Default false.' },
+            scope: { type: 'string', enum: ['own', 'global', 'both'], description: 'Default: both.' },
+          },
+        },
+      },
+      handle: async (input) => {
+        const { pinned_only, scope } = input as {
+          pinned_only?: boolean;
+          scope?: 'own' | 'global' | 'both';
+        };
+        const blocks = await store.listBlocks({
+          pinned: pinned_only,
+          scope: scope ?? 'both',
+        });
+        if (!blocks.length) return '(no blocks)';
+        return blocks
+          .map((b) => {
+            const v = typeof b.value === 'string' ? b.value : JSON.stringify(b.value);
+            const short = v.length > 120 ? v.slice(0, 120) + '…' : v;
+            return `- ${b.key}: ${short}`;
+          })
+          .join('\n');
+      },
+    },
+    {
+      def: {
+        name: 'memory_search',
+        description: searchDescription,
+        input_schema: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Free-text query' },
+            limit: { type: 'number', description: 'Max hits to return (1-15). Default 6.' },
+          },
+          required: ['query'],
+        },
+      },
+      handle: async (input) => {
+        const { query, limit } = input as { query: string; limit?: number };
+        const hits = await store.search(query, Math.min(15, Math.max(1, limit ?? 6)));
+        if (!hits.length) return '(no hits)';
+        return hits
+          .filter((h) => h.fact && h.invalid_at == null)
+          .map((h) => `- ${h.fact}${h.score != null ? ` (score=${h.score.toFixed(2)})` : ''}`)
+          .join('\n') || '(no current facts)';
+      },
+    },
+    {
+      def: {
+        name: 'memory_remember_block',
+        description:
+          'Store a first-person fact about the user as a memory block (key/value). Use for preferences, identity, current focus, routines — anything the user asserts about themselves. Block values REPLACE on write. Pin=true to inject into every future system prompt.',
+        input_schema: {
+          type: 'object',
+          properties: {
+            key: { type: 'string', description: 'Dotted key, e.g. preferences.language / persona.role / state.current_project' },
+            value: { description: 'String or JSON object — the value to store verbatim.' },
+            pinned: { type: 'boolean', description: 'If true, auto-injected into every future prompt. Use for stable identity / preferences only.' },
+            description: { type: 'string', description: 'Optional human-readable note about why this block exists.' },
+          },
+          required: ['key', 'value'],
+        },
+      },
+      handle: async (input) => {
+        const { key, value, pinned, description } = input as {
+          key: string;
+          value: unknown;
+          pinned?: boolean;
+          description?: string;
+        };
+        const ok = await store.putBlock(key, value, { pinned, description });
+        return ok ? `saved block: ${key}${pinned ? ' (pinned)' : ''}` : 'block save failed';
+      },
+    },
+    {
+      def: {
+        name: 'memory_remember_event',
+        description: episodeDescription,
+        input_schema: {
+          type: 'object',
+          properties: {
+            content: { type: 'string', description: 'Short statement of the fact, with explicit subject (name them, do not say "I" / "me").' },
+            tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags like "preference" / "decision".' },
+          },
+          required: ['content'],
+        },
+      },
+      handle: async (input) => {
+        const { content, tags } = input as { content: string; tags?: string[] };
+        const ok = await store.writeEpisode({ content, tags, source_type: 'text' });
+        return ok ? 'event recorded' : 'event write failed';
+      },
+    },
+  ];
+}

package/lib/chat/protocols/http.ts

@@ -0,0 +1,118 @@
+/**
+ * HTTP protocol runtime for connector tools.
+ *
+ * Issues an HTTP request from Forge (server-side, not the user's browser).
+ * Used by tools where the upstream offers a clean REST API and no DOM
+ * scraping is needed (GitHub API, GitLab API, internal services).
+ *
+ * Templates: {base_url}, {settings.*}, {args.*} are expanded into url,
+ * query values, header values, and body. Body can be a string or an
+ * object — strings are sent as-is after expansion; objects are walked
+ * and any string leaves are expanded, then JSON.stringify'd.
+ *
+ * Response: the body is returned verbatim (truncated to 8 KB for the
+ * LLM context) with a status-line preamble. Non-2xx is surfaced as
+ * is_error so the LLM can react.
+ */
+
+import type { HttpRequestSpec, ConnectorTool } from '../../plugins/types';
+import { expandAllTokens } from '../../plugins/templates';
+
+export interface HttpProtocolArgs {
+  tool: ConnectorTool;
+  settings: Record<string, any>;
+  args: Record<string, any>;
+}
+
+export interface HttpProtocolResult {
+  content: string;
+  is_error?: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 300_000;
+const MAX_BODY_BYTES = 8 * 1024;
+
+function expandObjectLeaves(obj: any, settings: Record<string, any>, args: Record<string, any>): any {
+  if (obj == null) return obj;
+  if (typeof obj === 'string') return expandAllTokens(obj, settings, args);
+  if (Array.isArray(obj)) return obj.map((v) => expandObjectLeaves(v, settings, args));
+  if (typeof obj === 'object') {
+    const out: Record<string, any> = {};
+    for (const [k, v] of Object.entries(obj)) out[k] = expandObjectLeaves(v, settings, args);
+    return out;
+  }
+  return obj;
+}
+
+function buildUrl(spec: HttpRequestSpec, settings: Record<string, any>, args: Record<string, any>): string {
+  const base = expandAllTokens(spec.url, settings, args);
+  if (!spec.query) return base;
+  const url = new URL(base);
+  for (const [k, raw] of Object.entries(spec.query)) {
+    const v = expandAllTokens(String(raw), settings, args);
+    url.searchParams.append(k, v);
+  }
+  return url.toString();
+}
+
+function buildHeaders(spec: HttpRequestSpec, settings: Record<string, any>, args: Record<string, any>): Headers {
+  const h = new Headers();
+  if (spec.headers) {
+    for (const [k, raw] of Object.entries(spec.headers)) {
+      h.set(k, expandAllTokens(String(raw), settings, args));
+    }
+  }
+  return h;
+}
+
+function buildBody(spec: HttpRequestSpec, settings: Record<string, any>, args: Record<string, any>): { body?: string; contentType?: string } {
+  if (spec.body == null) return {};
+  if (typeof spec.body === 'string') {
+    return { body: expandAllTokens(spec.body, settings, args) };
+  }
+  const obj = expandObjectLeaves(spec.body, settings, args);
+  return { body: JSON.stringify(obj), contentType: 'application/json' };
+}
+
+function truncate(s: string): { text: string; truncated: boolean; totalBytes: number } {
+  const buf = Buffer.from(s, 'utf-8');
+  if (buf.byteLength <= MAX_BODY_BYTES) return { text: s, truncated: false, totalBytes: buf.byteLength };
+  const slice = buf.subarray(0, MAX_BODY_BYTES).toString('utf-8');
+  return { text: slice, truncated: true, totalBytes: buf.byteLength };
+}
+
+export async function runHttp({ tool, settings, args }: HttpProtocolArgs): Promise<HttpProtocolResult> {
+  const spec = tool.request;
+  if (!spec || !spec.url) {
+    return { content: 'http tool missing `request.url`', is_error: true };
+  }
+  const method = (spec.method || 'GET').toUpperCase();
+  const timeoutMs = Math.min(MAX_TIMEOUT_MS, Math.max(1, Number(tool.timeout_ms || DEFAULT_TIMEOUT_MS)));
+
+  const url = buildUrl(spec, settings, args);
+  const headers = buildHeaders(spec, settings, args);
+  const { body, contentType } = buildBody(spec, settings, args);
+  if (body != null && contentType && !headers.has('content-type')) headers.set('content-type', contentType);
+
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+
+  let res: Response;
+  try {
+    res = await fetch(url, { method, headers, body, signal: controller.signal });
+  } catch (e) {
+    clearTimeout(timer);
+    return { content: `http request failed: ${(e as Error).message}`, is_error: true };
+  }
+  clearTimeout(timer);
+
+  const text = await res.text().catch(() => '');
+  const { text: shown, truncated, totalBytes } = truncate(text);
+  const preamble = `HTTP ${res.status} ${res.statusText} · ${method} ${url}\n` +
+                   (truncated ? `(showing ${MAX_BODY_BYTES} of ${totalBytes} bytes — truncated)\n\n` : '\n');
+  return {
+    content: preamble + shown,
+    is_error: !res.ok,
+  };
+}

package/lib/chat/protocols/shell.ts

@@ -0,0 +1,101 @@
+/**
+ * Shell protocol runtime for connector tools.
+ *
+ * Spawns a process with an explicit arg array (no shell:true) so
+ * templated values can never inject shell metacharacters. Each arg
+ * is templated independently — e.g. `["git", "-C", "{args.repo}",
+ * "log", "-n", "{args.n}"]` produces a literal arg, not a shell line.
+ *
+ * Returns combined output. Non-zero exit code is surfaced as is_error
+ * with the exit code in the preamble and stderr if any.
+ *
+ * Safety boundary: connectors are user-installed manifests. A malicious
+ * yaml could still pick a destructive `command[0]` (rm, etc.), so
+ * shell-protocol tools must be reviewed at install time. There's no
+ * automatic command allow-list in v1.
+ */
+
+import type { ConnectorTool } from '../../plugins/types';
+import { expandAllTokens } from '../../plugins/templates';
+import { spawn } from 'node:child_process';
+
+export interface ShellProtocolArgs {
+  tool: ConnectorTool;
+  settings: Record<string, any>;
+  args: Record<string, any>;
+}
+
+export interface ShellProtocolResult {
+  content: string;
+  is_error?: boolean;
+}
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const MAX_TIMEOUT_MS = 300_000;
+const MAX_OUTPUT_BYTES = 8 * 1024;
+
+function truncate(s: string): string {
+  const buf = Buffer.from(s, 'utf-8');
+  if (buf.byteLength <= MAX_OUTPUT_BYTES) return s;
+  return buf.subarray(0, MAX_OUTPUT_BYTES).toString('utf-8') +
+         `\n(...truncated, total ${buf.byteLength} bytes)`;
+}
+
+export async function runShell({ tool, settings, args }: ShellProtocolArgs): Promise<ShellProtocolResult> {
+  const cmd = tool.command;
+  if (!cmd || !Array.isArray(cmd) || cmd.length === 0) {
+    return { content: 'shell tool missing `command` array', is_error: true };
+  }
+  const expanded = cmd.map((part) => expandAllTokens(String(part), settings, args));
+  const [bin, ...argv] = expanded;
+  const cwd = tool.cwd ? expandAllTokens(tool.cwd, settings, args) : undefined;
+  const env = tool.env
+    ? Object.fromEntries(Object.entries(tool.env).map(([k, v]) => [k, expandAllTokens(String(v), settings, args)]))
+    : undefined;
+  const timeoutMs = Math.min(MAX_TIMEOUT_MS, Math.max(1, Number(tool.timeout_ms || DEFAULT_TIMEOUT_MS)));
+
+  return new Promise<ShellProtocolResult>((resolve) => {
+    let proc;
+    try {
+      proc = spawn(bin!, argv, {
+        cwd,
+        env: env ? { ...process.env, ...env } : process.env,
+        stdio: ['ignore', 'pipe', 'pipe'],
+      });
+    } catch (e) {
+      return resolve({ content: `shell spawn failed: ${(e as Error).message}`, is_error: true });
+    }
+
+    let stdout = '';
+    let stderr = '';
+    let killed = false;
+    const timer = setTimeout(() => {
+      killed = true;
+      try { proc.kill('SIGTERM'); } catch {}
+    }, timeoutMs);
+
+    proc.stdout?.on('data', (b) => { stdout += b.toString('utf-8'); });
+    proc.stderr?.on('data', (b) => { stderr += b.toString('utf-8'); });
+
+    proc.on('error', (err) => {
+      clearTimeout(timer);
+      resolve({ content: `shell error: ${err.message}`, is_error: true });
+    });
+
+    proc.on('close', (code, signal) => {
+      clearTimeout(timer);
+      const preamble = killed
+        ? `[killed after ${timeoutMs}ms]\n`
+        : signal
+          ? `[signal ${signal}]\n`
+          : code === 0
+            ? ''
+            : `[exit ${code}]\n`;
+      const trail = stderr.trim() && code !== 0 ? `\n--- stderr ---\n${truncate(stderr)}` : '';
+      resolve({
+        content: preamble + truncate(stdout) + trail,
+        is_error: killed || code !== 0,
+      });
+    });
+  });
+}

package/lib/chat/proxy.ts

@@ -0,0 +1,51 @@
+/**
+ * Thin proxy helper — forwards a Next.js request to chat-standalone
+ * (127.0.0.1:$CHAT_PORT, default 8408). Auth is enforced by the Next
+ * middleware before we get here; chat-standalone itself is loopback-only.
+ */
+
+const CHAT_PORT = Number(process.env.CHAT_PORT) || 8408;
+
+export async function proxyToChat(req: Request, path: string): Promise<Response> {
+  const url = new URL(req.url);
+  const target = `http://127.0.0.1:${CHAT_PORT}${path}${url.search || ''}`;
+
+  // Pass the body through verbatim for POST/PATCH. GET/DELETE go without.
+  const init: RequestInit = {
+    method: req.method,
+    headers: { 'content-type': 'application/json' },
+    body: req.method === 'GET' || req.method === 'DELETE' || req.method === 'HEAD'
+      ? undefined
+      : await req.text(),
+  };
+
+  let upstream: Response;
+  try {
+    upstream = await fetch(target, init);
+  } catch (e) {
+    return new Response(JSON.stringify({ error: `chat service unreachable on ${CHAT_PORT}: ${(e as Error).message}` }), {
+      status: 502, headers: { 'content-type': 'application/json' },
+    });
+  }
+
+  // For SSE streams, pipe the body through as a streaming response so
+  // events reach the browser as they arrive.
+  const ct = upstream.headers.get('content-type') || '';
+  if (ct.startsWith('text/event-stream') && upstream.body) {
+    return new Response(upstream.body, {
+      status: upstream.status,
+      headers: {
+        'content-type': 'text/event-stream',
+        'cache-control': 'no-cache, no-transform',
+        'connection': 'keep-alive',
+        'x-accel-buffering': 'no',
+      },
+    });
+  }
+
+  const body = await upstream.text();
+  return new Response(body, {
+    status: upstream.status,
+    headers: { 'content-type': upstream.headers.get('content-type') || 'application/json' },
+  });
+}