@tangle-network/starter-foundry 0.7.2 → 0.13.0

package/registry/layers/agent-base/mcp-registry/files/lib/mcp/register.ts

@@ -0,0 +1,130 @@
+// agent-base:mcp-registry — runtime helpers for MCP server registration.
+//
+// At deploy time the bundle ships `<workspace.root>/.mcp.json` with the
+// templated server set. Most agents only need that static file: Claude Code
+// and OpenCode both auto-discover `.mcp.json` from the workspace root.
+//
+// These helpers exist for the cases where the resident agent must mutate the
+// registry at runtime — adding a server after a credential is minted, or
+// pruning servers it doesn't need from a starter template. Composes with
+// `agent-base:secure` (load credentials via `loadSecret(...)` from
+// `src/lib/secure/secrets.ts` rather than embedding them in `.mcp.json`).
+//
+// File contract verified against:
+// - Claude Code: https://docs.claude.com/en/docs/claude-code/mcp
+// - OpenCode  : `AgentProfile.mcp` shape in `@tangle-network/sandbox/agent-profile.ts`
+
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+
+/**
+ * Shape of one MCP server entry. Mirrors the `AgentProfileMcpServer` contract
+ * from `@tangle-network/sandbox` (provider-neutral) plus the documented
+ * Claude Code / OpenCode native fields.
+ */
+export interface McpServerConfig {
+  transport?: 'stdio' | 'sse' | 'http'
+  command?: string
+  args?: string[]
+  env?: Record<string, string>
+  cwd?: string
+  url?: string
+  headers?: Record<string, string>
+  enabled?: boolean
+}
+
+/**
+ * Top-level shape of `.mcp.json`. Both Claude Code and OpenCode read
+ * `mcpServers` as the top-level key.
+ */
+export interface McpRegistry {
+  mcpServers: Record<string, McpServerConfig>
+}
+
+/**
+ * Default registry path inside the sandbox workspace.
+ *
+ * The deploy script's `--harness <name>` flag may override this — callers that
+ * need the actual path at runtime should read it from the bundle's manifest
+ * `defaults.mcpRegistryPath` rather than hardcoding.
+ */
+export const DEFAULT_REGISTRY_PATH = '/home/agent/.mcp.json'
+
+/**
+ * Read the current registry from disk. Returns an empty `mcpServers` map if
+ * the file does not exist.
+ */
+export async function readRegistry(path: string = DEFAULT_REGISTRY_PATH): Promise<McpRegistry> {
+  try {
+    const raw = await readFile(path, 'utf8')
+    const parsed = JSON.parse(raw) as Partial<McpRegistry>
+    return { mcpServers: parsed.mcpServers ?? {} }
+  } catch (err) {
+    const code = (err as NodeJS.ErrnoException | undefined)?.code
+    if (code === 'ENOENT') return { mcpServers: {} }
+    throw err
+  }
+}
+
+/**
+ * Atomically rewrite the registry on disk. Writes to a sibling tempfile and
+ * renames into place to avoid the harness reading a half-written file.
+ */
+export async function writeRegistry(
+  registry: McpRegistry,
+  path: string = DEFAULT_REGISTRY_PATH,
+): Promise<void> {
+  const tmp = join(path + '.tmp')
+  await writeFile(tmp, JSON.stringify(registry, null, 2) + '\n', 'utf8')
+  const { rename } = await import('node:fs/promises')
+  await rename(tmp, path)
+}
+
+/**
+ * Add (or overwrite) a single server entry. Returns the updated registry.
+ *
+ * This is intentionally an explicit overwrite — the caller must opt out of
+ * replacement by checking `name in registry.mcpServers` first if they want
+ * a non-destructive add.
+ */
+export async function addServer(
+  name: string,
+  config: McpServerConfig,
+  path: string = DEFAULT_REGISTRY_PATH,
+): Promise<McpRegistry> {
+  const registry = await readRegistry(path)
+  registry.mcpServers[name] = config
+  await writeRegistry(registry, path)
+  return registry
+}
+
+/**
+ * Remove a single server entry by name. No-op when the name is absent.
+ */
+export async function removeServer(
+  name: string,
+  path: string = DEFAULT_REGISTRY_PATH,
+): Promise<McpRegistry> {
+  const registry = await readRegistry(path)
+  delete registry.mcpServers[name]
+  await writeRegistry(registry, path)
+  return registry
+}
+
+/**
+ * Keep only the named servers; drop everything else. Used at agent startup
+ * when the bundle ships a starter template with N servers and the resident
+ * agent only needs a subset.
+ */
+export async function keepServers(
+  names: readonly string[],
+  path: string = DEFAULT_REGISTRY_PATH,
+): Promise<McpRegistry> {
+  const registry = await readRegistry(path)
+  const keep = new Set(names)
+  for (const existing of Object.keys(registry.mcpServers)) {
+    if (!keep.has(existing)) delete registry.mcpServers[existing]
+  }
+  await writeRegistry(registry, path)
+  return registry
+}

package/registry/layers/agent-base/mcp-registry/manifest.json

@@ -0,0 +1,109 @@
+{
+  "id": "mcp-registry",
+  "slot": "agent-base",
+  "description": "MCP server registry. Ships a .mcp.json template at <workspace.root>/.mcp.json with env-var-driven server config. Composes with agent-base:secure for credential injection. Harness-aware: deploy script translates the file path/format per target harness (Claude Code + OpenCode read .mcp.json natively; Hermes path is partial \u2014 see docs/issues/sandbox-sdk-deploy-hooks.md).",
+  "appliesTo": [
+    "agent-runtime-account-executive-ts",
+    "agent-runtime-architect-ts",
+    "agent-runtime-auditor-ts",
+    "agent-runtime-biology-research-ts",
+    "agent-runtime-business-partner-ts",
+    "agent-runtime-career-coach-ts",
+    "agent-runtime-chef-ts",
+    "agent-runtime-chemistry-research-ts",
+    "agent-runtime-cmo-advisor-ts",
+    "agent-runtime-college-counselor-ts",
+    "agent-runtime-cs-research-ts",
+    "agent-runtime-cs-tutor-ts",
+    "agent-runtime-customer-success-ts",
+    "agent-runtime-data-analyst-ts",
+    "agent-runtime-designer-ts",
+    "agent-runtime-devops-ts",
+    "agent-runtime-doctor-ts",
+    "agent-runtime-engineering-manager-ts",
+    "agent-runtime-essay-coach-ts",
+    "agent-runtime-financial-analyst-ts",
+    "agent-runtime-fitness-coach-ts",
+    "agent-runtime-friend-ts",
+    "agent-runtime-game-designer-ts",
+    "agent-runtime-grant-writer-ts",
+    "agent-runtime-history-tutor-ts",
+    "agent-runtime-illustrator-ts",
+    "agent-runtime-language-tutor-ts",
+    "agent-runtime-legal-counsel-ts",
+    "agent-runtime-math-research-ts",
+    "agent-runtime-math-tutor-ts",
+    "agent-runtime-mediator-ts",
+    "agent-runtime-meditation-coach-ts",
+    "agent-runtime-ml-research-ts",
+    "agent-runtime-music-producer-ts",
+    "agent-runtime-novelist-coach-ts",
+    "agent-runtime-nutritionist-ts",
+    "agent-runtime-pentester-ts",
+    "agent-runtime-pharmacist-ts",
+    "agent-runtime-photographer-ts",
+    "agent-runtime-physics-research-ts",
+    "agent-runtime-product-manager-ts",
+    "agent-runtime-real-estate-ts",
+    "agent-runtime-recruiter-ts",
+    "agent-runtime-relationship-coach-ts",
+    "agent-runtime-research",
+    "agent-runtime-sales-engineer-ts",
+    "agent-runtime-screenwriter-ts",
+    "agent-runtime-security-engineer-ts",
+    "agent-runtime-tax-ts",
+    "agent-runtime-therapist-ts",
+    "agent-runtime-travel-planner-ts",
+    "agent-runtime-veterinarian-ts",
+    "agent-runtime-wealth-manager-ts",
+    "multi-agent-creative-studio-ts",
+    "multi-agent-legal-ops-ts",
+    "multi-agent-product-ops-ts",
+    "multi-agent-research-lab-ts",
+    "multi-agent-startup-team-ts"
+  ],
+  "provides": [
+    "mcp:registry"
+  ],
+  "requires": [],
+  "defaults": {
+    "mcpRegistryPath": "/home/agent/.mcp.json",
+    "mcpServers": [
+      "filesystem",
+      "fetch",
+      "github",
+      "memory",
+      "scheduler"
+    ]
+  },
+  "files": [
+    {
+      "source": "files/.mcp.json",
+      "target": ".mcp.json"
+    },
+    {
+      "source": "files/lib/mcp/register.ts",
+      "target": "src/lib/mcp/register.ts"
+    },
+    {
+      "source": "files/lib/mcp/README.md",
+      "target": "src/lib/mcp/README.md"
+    }
+  ],
+  "validationChecks": [
+    {
+      "type": "file-exists",
+      "path": ".mcp.json"
+    },
+    {
+      "type": "file-exists",
+      "path": "src/lib/mcp/register.ts"
+    }
+  ],
+  "contextHints": {
+    "extensionPoints": [
+      "src/lib/mcp/"
+    ],
+    "commands": []
+  }
+}

package/registry/layers/agent-base/memory/files/lib/memory/grep.ts

@@ -0,0 +1,126 @@
+// memory/grep — zero-dep filesystem grep across conversation .md files.
+//
+// Case-insensitive substring match. Per-turn scoring: score = number of
+// non-overlapping occurrences of the query in the turn's content. Ties
+// across turns are broken by recency (file mtime, newer first). Returns
+// up to `k` hits.
+//
+// No vector store. No embeddings. No third-party deps. The bundle's
+// resident agent does the semantic-search work via its own LLM after
+// this returns candidate turns.
+
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { join } from 'node:path'
+import type { SearchHit } from './types.js'
+import { parseConversation } from './index.js'
+
+interface ScoredHit extends SearchHit {
+  /** mtime epoch ms — used only for tie-breaking, not exposed to caller. */
+  _mtime: number
+}
+
+/**
+ * Filesystem grep across conversation .md files in `dir`.
+ *
+ * Matching: case-insensitive substring, on the per-turn `content` field.
+ * Scoring: number of non-overlapping query occurrences in the turn.
+ * Snippet: ±50 chars around the FIRST match in the turn, trimmed to
+ * line boundaries where possible, with original casing preserved.
+ *
+ * Performance: O(N) over total conversation bytes — we read every file.
+ * Acceptable up to roughly 10K threads × 100KB each (~1GB scan, ~2-5s
+ * wall on local SSD). At larger scales, swap this for a sibling
+ * vector-store layer.
+ *
+ * @public
+ */
+export async function grepSearch(query: string, dir: string, k: number): Promise<SearchHit[]> {
+  const q = query.toLowerCase()
+  if (q.length === 0 || k <= 0) return []
+
+  let entries: string[]
+  try {
+    entries = await readdir(dir)
+  } catch (err: unknown) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw err
+  }
+
+  const hits: ScoredHit[] = []
+  for (const e of entries) {
+    if (!e.endsWith('.md')) continue
+    const path = join(dir, e)
+    let st: Awaited<ReturnType<typeof stat>>
+    let text: string
+    try {
+      st = await stat(path)
+      if (!st.isFile()) continue
+      text = await readFile(path, 'utf8')
+    } catch {
+      continue
+    }
+    const threadId = e.slice(0, -3)
+    const conv = parseConversation(threadId, text)
+    const mtime = st.mtime.getTime()
+
+    for (let i = 0; i < conv.turns.length; i++) {
+      const turn = conv.turns[i]
+      if (!turn) continue
+      const lower = turn.content.toLowerCase()
+      const score = countOccurrences(lower, q)
+      if (score === 0) continue
+      const firstAt = lower.indexOf(q)
+      const snippet = makeSnippet(turn.content, firstAt, q.length)
+      hits.push({
+        threadId,
+        turnIdx: i,
+        snippet,
+        score,
+        _mtime: mtime,
+      })
+    }
+  }
+
+  hits.sort((a, b) => {
+    if (b.score !== a.score) return b.score - a.score
+    return b._mtime - a._mtime
+  })
+
+  return hits.slice(0, k).map(({ _mtime: _m, ...rest }) => rest)
+}
+
+/**
+ * Count non-overlapping occurrences of `needle` (already lowercased) in
+ * `haystack` (already lowercased). Empty needle returns 0.
+ */
+function countOccurrences(haystack: string, needle: string): number {
+  if (needle.length === 0) return 0
+  let count = 0
+  let from = 0
+  while (true) {
+    const idx = haystack.indexOf(needle, from)
+    if (idx === -1) break
+    count++
+    from = idx + needle.length
+  }
+  return count
+}
+
+/**
+ * Build a ~100-char snippet centered on the first match. Original casing
+ * preserved. Snippet is trimmed to line boundaries when those fall
+ * within the window so we don't emit half-words. Prepends `…` / appends
+ * `…` when truncating.
+ */
+function makeSnippet(content: string, matchStart: number, matchLen: number): string {
+  const RADIUS = 50
+  const start = Math.max(0, matchStart - RADIUS)
+  const end = Math.min(content.length, matchStart + matchLen + RADIUS)
+  // Collapse all internal whitespace to single spaces so the snippet is a
+  // single line, regardless of where the radius landed inside multi-line
+  // content. Trim leading/trailing whitespace from the windowed slice.
+  const slice = content.slice(start, end).replace(/\s+/g, ' ').trim()
+  const prefix = start > 0 ? '…' : ''
+  const suffix = end < content.length ? '…' : ''
+  return `${prefix}${slice}${suffix}`
+}

package/registry/layers/agent-base/memory/files/lib/memory/index.test.ts

@@ -0,0 +1,216 @@
+// Tests for agent-base:memory. Real filesystem (per-test temp dir), no
+// mocks — the layer is a thin wrapper around node:fs/promises and the
+// tests must exercise the actual disk path.
+//
+// Run with: tsx --test registry/layers/agent-base/memory/files/lib/memory/index.test.ts
+
+import assert from 'node:assert/strict'
+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { test } from 'node:test'
+
+import {
+  appendTurn,
+  getConversation,
+  listThreads,
+  searchConversations,
+} from './index.js'
+
+function freshDir(): string {
+  const d = mkdtempSync(join(tmpdir(), 'memory-test-'))
+  process.env.CONVERSATIONS_DIR = d
+  return d
+}
+
+const ts = (offsetMs = 0): string => new Date(Date.now() + offsetMs).toISOString()
+
+// ── appendTurn ───────────────────────────────────────────────────────────
+
+test('appendTurn: creates file and conversations dir if missing', async () => {
+  const dir = freshDir()
+  await appendTurn('chat-1', { ts: ts(), role: 'user', content: 'hello' })
+  const raw = readFileSync(join(dir, 'chat-1.md'), 'utf8')
+  assert.match(raw, /\nrole: user\n/)
+  assert.match(raw, /\nhello\n/)
+})
+
+test('appendTurn: appends additional turns to an existing thread', async () => {
+  freshDir()
+  await appendTurn('chat-2', { ts: ts(), role: 'user', content: 'first' })
+  await appendTurn('chat-2', { ts: ts(1), role: 'assistant', content: 'second' })
+  await appendTurn('chat-2', { ts: ts(2), role: 'user', content: 'third' })
+  const conv = await getConversation('chat-2')
+  assert.ok(conv)
+  assert.equal(conv.turns.length, 3)
+  assert.deepEqual(
+    conv.turns.map((t) => [t.role, t.content]),
+    [
+      ['user', 'first'],
+      ['assistant', 'second'],
+      ['user', 'third'],
+    ],
+  )
+})
+
+test('appendTurn: rejects path-traversal threadIds', async () => {
+  freshDir()
+  await assert.rejects(
+    () => appendTurn('../escape', { ts: ts(), role: 'user', content: 'x' }),
+    /invalid threadId/,
+  )
+  await assert.rejects(
+    () => appendTurn('a/b', { ts: ts(), role: 'user', content: 'x' }),
+    /invalid threadId/,
+  )
+  await assert.rejects(
+    () => appendTurn('', { ts: ts(), role: 'user', content: 'x' }),
+    /non-empty/,
+  )
+})
+
+test('appendTurn: rejects invalid role', async () => {
+  freshDir()
+  await assert.rejects(
+    () =>
+      appendTurn('chat-3', {
+        ts: ts(),
+        // @ts-expect-error — testing runtime guard
+        role: 'admin',
+        content: 'x',
+      }),
+    /invalid role/,
+  )
+})
+
+test('appendTurn: persists metadata when supplied', async () => {
+  freshDir()
+  await appendTurn('chat-meta', {
+    ts: ts(),
+    role: 'user',
+    content: 'hi',
+    metadata: { channel: 'telegram', userId: 42 },
+  })
+  const conv = await getConversation('chat-meta')
+  assert.ok(conv)
+  assert.equal(conv.channel, 'telegram')
+  assert.deepEqual(conv.turns[0]?.metadata, { channel: 'telegram', userId: 42 })
+})
+
+// ── getConversation ──────────────────────────────────────────────────────
+
+test('getConversation: parses ts/role/content correctly', async () => {
+  freshDir()
+  const t = ts()
+  await appendTurn('chat-4', { ts: t, role: 'system', content: 'sys-prompt\nwith\nlines' })
+  const conv = await getConversation('chat-4')
+  assert.ok(conv)
+  assert.equal(conv.threadId, 'chat-4')
+  assert.equal(conv.turns.length, 1)
+  assert.equal(conv.turns[0]?.ts, t)
+  assert.equal(conv.turns[0]?.role, 'system')
+  assert.equal(conv.turns[0]?.content, 'sys-prompt\nwith\nlines')
+  assert.equal(conv.startedAt, t)
+})
+
+test('getConversation: returns null for missing thread', async () => {
+  freshDir()
+  const conv = await getConversation('does-not-exist')
+  assert.equal(conv, null)
+})
+
+test('getConversation: skips malformed blocks gracefully', async () => {
+  const dir = freshDir()
+  // Write a file with one good block, one block missing role, one good block.
+  const file = join(dir, 'chat-malformed.md')
+  const content =
+    '\n---\nts: 2026-04-26T00:00:00.000Z\nrole: user\n---\n\ngood-1\n' +
+    '\n---\nts: 2026-04-26T00:01:00.000Z\n---\n\nmissing-role\n' +
+    '\n---\nts: 2026-04-26T00:02:00.000Z\nrole: assistant\n---\n\ngood-2\n'
+  writeFileSync(file, content)
+  const conv = await getConversation('chat-malformed')
+  assert.ok(conv)
+  assert.equal(conv.turns.length, 2)
+  assert.equal(conv.turns[0]?.content, 'good-1')
+  assert.equal(conv.turns[1]?.content, 'good-2')
+})
+
+// ── listThreads ──────────────────────────────────────────────────────────
+
+test('listThreads: empty when conversations dir does not exist', async () => {
+  process.env.CONVERSATIONS_DIR = join(tmpdir(), 'memory-no-such-dir-' + Date.now())
+  const out = await listThreads()
+  assert.deepEqual(out, [])
+})
+
+test('listThreads: sorted by lastModified DESC', async () => {
+  freshDir()
+  await appendTurn('alpha', { ts: ts(), role: 'user', content: 'a' })
+  // Force monotonic mtime ordering: small wait to let mtime tick.
+  await new Promise((r) => setTimeout(r, 15))
+  await appendTurn('beta', { ts: ts(), role: 'user', content: 'b' })
+  await new Promise((r) => setTimeout(r, 15))
+  await appendTurn('gamma', { ts: ts(), role: 'user', content: 'g' })
+  const threads = await listThreads()
+  assert.deepEqual(
+    threads.map((t) => t.threadId),
+    ['gamma', 'beta', 'alpha'],
+  )
+  // Each entry has a parseable ISO timestamp.
+  for (const t of threads) {
+    assert.equal(new Date(t.lastModified).toString() !== 'Invalid Date', true)
+  }
+})
+
+// ── searchConversations ──────────────────────────────────────────────────
+
+test('searchConversations: returns hits ordered by score, then recency', async () => {
+  freshDir()
+  await appendTurn('thread-old', { ts: ts(), role: 'user', content: 'tangle is great' })
+  await new Promise((r) => setTimeout(r, 15))
+  await appendTurn('thread-new', {
+    ts: ts(),
+    role: 'user',
+    content: 'tangle tangle tangle — best framework ever (tangle wins)',
+  })
+  const hits = await searchConversations('tangle')
+  assert.ok(hits.length >= 2)
+  // Highest score first
+  assert.equal(hits[0]?.threadId, 'thread-new')
+  assert.equal(hits[0]?.score, 4)
+  assert.equal(hits[1]?.threadId, 'thread-old')
+  assert.equal(hits[1]?.score, 1)
+  // Snippet contains the match (case-preserved)
+  assert.match(hits[0]!.snippet, /tangle/i)
+})
+
+test('searchConversations: empty array when no matches', async () => {
+  freshDir()
+  await appendTurn('thread-q', { ts: ts(), role: 'user', content: 'just some text' })
+  const hits = await searchConversations('zzzzzzz-no-match')
+  assert.deepEqual(hits, [])
+})
+
+test('searchConversations: empty/whitespace query returns []', async () => {
+  freshDir()
+  await appendTurn('thread-q2', { ts: ts(), role: 'user', content: 'anything' })
+  assert.deepEqual(await searchConversations(''), [])
+  assert.deepEqual(await searchConversations('   '), [])
+})
+
+test('searchConversations: case-insensitive match, original casing in snippet', async () => {
+  freshDir()
+  await appendTurn('case', { ts: ts(), role: 'user', content: 'The Quick Brown FOX jumps' })
+  const hits = await searchConversations('fox')
+  assert.equal(hits.length, 1)
+  assert.match(hits[0]!.snippet, /FOX/)
+})
+
+test('searchConversations: respects k', async () => {
+  freshDir()
+  for (const id of ['a', 'b', 'c', 'd']) {
+    await appendTurn(id, { ts: ts(), role: 'user', content: 'matchword' })
+  }
+  const hits = await searchConversations('matchword', 2)
+  assert.equal(hits.length, 2)
+})