@11agents/cli 0.1.2 → 0.1.4

package/README.md

@@ -60,10 +60,21 @@ Background mode writes its pid to `~/.11agents/daemon.pid` and logs to `~/.11age
 Useful daemon options:
 
 ```bash
-11agents daemon start --heartbeat-interval 15 --scan-interval 60 --task-interval 15
+11agents daemon start --heartbeat-interval 15 --scan-interval 60 --task-interval 15 --project-refresh-interval 1800
 11agents daemon start --handler ./worker.js
 ```
 
+On startup, and every 30 minutes after that, the daemon syncs project metadata and prepares local project headquarters:
+
+- Project headquarters: `~/.11agents/<project>/`
+- Project knowledge base: `~/.11agents/<project>/knowledge_base/`
+- Agent QMD memory: `~/.11agents/<project>/agents/<agent>/memory/`
+- Agent-local skills: `~/.11agents/<project>/agents/<agent>/skills/`
+- Cloud database snapshot: `~/.11agents/<project>/database/snapshot.json`
+- Task scratch directory: `~/.11agents/<project>/tmp/<taskId>/`
+
+Codex runs from `~/.11agents/<project>/` by default. Treat that directory as read-only project context. Task code may write temporary files only under `./tmp/<taskId>/`; the daemon removes that task scratch directory after the task finishes. Agent environment variables from the control plane are injected into the Codex child process and are not written to disk.
+
 The built-in task runner currently supports Codex tasks. A custom handler may export:
 
 ```js
@@ -76,6 +87,18 @@ export async function handleRuntimeTask(task) {
 }
 ```
 
+## MCP Project Sync Server
+
+Run the local MCP server over stdio:
+
+```bash
+11agents mcp start
+```
+
+Configure your MCP client to run that command and pass the project token when calling tools. The server exposes:
+
+- `knowledge_sync` — pull/push the project knowledge base between cloud and `~/.11agents/<project>/knowledge_base/`.
+
 ## Telemetry Compatibility
 
 The package still includes the original `gtm-swarm` binary for swarm telemetry compatibility.

package/bin/11agents.js

@@ -2,12 +2,14 @@
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { parseArgs } from '../src/args.js'
+import { knowledgeStatus, syncKnowledge } from '../src/commands/knowledge.js'
 import { runNode } from '../src/commands/node.js'
 import { pushArtifact, pushBatch, pushObservation } from '../src/commands/push.js'
 import { registerRuntime, scanRuntime, startRuntimeDaemon } from '../src/commands/runtime.js'
 import { startBackgroundDaemon, statusBackgroundDaemon, stopBackgroundDaemon } from '../src/daemon-process.js'
 import { getControlConfig } from '../src/client.js'
 import { CLI_VERSION, printStartupInfo } from '../src/info.js'
+import { startMcpServer } from '../src/mcp.js'
 import { validateTelemetryBatch } from '../src/schema.js'
 
 function usage() {
@@ -17,14 +19,17 @@ Usage:
   11agents help
   11agents runtime scan
   11agents runtime register [--server <url>] [--token <token>] [--machine <key>]
-  11agents daemon start [--server <url>] [--token <token>] [--machine <key>] [--task-interval <seconds>] [--background]
+  11agents daemon start [--server <url>] [--token <token>] [--machine <key>] [--task-interval <seconds>] [--project-refresh-interval <seconds>] [--background]
   11agents daemon status
   11agents daemon stop
   11agents daemon start --handler ./worker.js  # optional custom worker override
+  11agents mcp start
   11agents validate <file>
   11agents push batch <file>
   11agents push artifact --workspace <slug> --agent <key> --platform x --type post --external-id <id>
   11agents push observation --workspace <slug> --agent <key> --platform x --type post --external-id <id> --metric views=123
+  11agents knowledge sync --project <slug> [--mode pull|push]
+  11agents knowledge status --project <slug>
   11agents node run --workspace <slug> --agent <key> --node <node-id> --handler ./collect-x.js [--once]
 
 Environment:
@@ -32,7 +37,14 @@ Environment:
   GTM_SWARM_SERVER     compatibility fallback for server URL
   GTM_WRITES_TOKEN     control-plane token for runtime registration
   ELEVENAGENTS_MACHINE stable machine key, defaults to hostname
-  GTM_SWARM_TOKEN      project swarm token for push/node commands`)
+  GTM_SWARM_TOKEN      project swarm token for push/node commands
+
+Runtime task workspace:
+  Daemon project headquarters live under ~/.11agents/<project>/.
+  Knowledge lives under knowledge_base/. Agent QMD memory lives under
+  agents/<agent>/memory/. Agent-local skills live under agents/<agent>/skills/.
+  Built-in Codex tasks run from ~/.11agents/<project>/ by default. Temporary
+  writes belong under ./tmp/<taskId>/ and are cleaned after the task finishes.`)
 }
 
 async function main() {
@@ -97,6 +109,11 @@ async function main() {
     return
   }
 
+  if (command === 'mcp' && (!subcommand || subcommand === 'start')) {
+    await startMcpServer()
+    return
+  }
+
   if (command === 'validate') {
     const file = subcommand
     if (!file) throw new Error('validate requires a file')
@@ -123,6 +140,16 @@ async function main() {
     return
   }
 
+  if (command === 'knowledge' && subcommand === 'sync') {
+    await syncKnowledge(flags)
+    return
+  }
+
+  if (command === 'knowledge' && subcommand === 'status') {
+    await knowledgeStatus(flags)
+    return
+  }
+
   if (command === 'node' && subcommand === 'run') {
     await runNode(flags)
     return

package/examples/voc-mcp-tool-call-batch.json

@@ -1,6 +1,7 @@
 {
   "schema_version": "swarm.telemetry.v1",
   "workspace": "voc-ai",
+  "agent_id": "voc-amazon-reviews-mcp-runtime",
   "agent_key": "voc-amazon-reviews-mcp",
   "node_id": "vercel-prod",
   "sent_at": "2026-05-25T10:00:02Z",

package/examples/x-agent-batch.json

@@ -1,6 +1,7 @@
 {
   "schema_version": "swarm.telemetry.v1",
   "workspace": "flatkey",
+  "agent_id": "agent-runtime-123",
   "agent_key": "x-growth-agent",
   "node_id": "mac-mini-01",
   "sent_at": "2026-05-25T09:30:00Z",

package/examples/x-observation-job-result.json

@@ -4,6 +4,7 @@
   "batch": {
     "schema_version": "swarm.telemetry.v1",
     "workspace": "flatkey",
+    "agent_id": "agent-runtime-123",
     "agent_key": "x-growth-agent",
     "node_id": "mac-mini-01",
     "sent_at": "2026-05-25T09:34:00Z",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@11agents/cli",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "11agents local runtime and telemetry CLI",
   "type": "module",
   "bin": {

package/src/commands/data-collection.js

@@ -0,0 +1,95 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { requestJson } from '../client.js'
+
+function slugify(value) {
+  return String(value || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+}
+
+function projectDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.11agents', slugify(project))
+}
+
+function formatsDir(project, options) {
+  return path.join(projectDir(project, options), 'data-formats')
+}
+
+function schemaPath(project, dataset, options) {
+  return path.join(formatsDir(project, options), `${slugify(dataset)}.json`)
+}
+
+function validateValue(value, schema, label) {
+  const type = schema?.type
+  if (!type) return
+  if (type === 'number' && typeof value !== 'number') throw new Error(`${label} must be number`)
+  if (type === 'integer' && (!Number.isInteger(value))) throw new Error(`${label} must be integer`)
+  if (type === 'string' && typeof value !== 'string') throw new Error(`${label} must be string`)
+  if (type === 'boolean' && typeof value !== 'boolean') throw new Error(`${label} must be boolean`)
+  if (type === 'array' && !Array.isArray(value)) throw new Error(`${label} must be array`)
+  if (type === 'object' && (typeof value !== 'object' || value === null || Array.isArray(value))) throw new Error(`${label} must be object`)
+}
+
+export function validateRowsAgainstSchema(rows, schema) {
+  if (!Array.isArray(rows)) throw new Error('rows must be an array')
+  const required = Array.isArray(schema?.required) ? schema.required : []
+  const properties = schema?.properties && typeof schema.properties === 'object' ? schema.properties : {}
+  rows.forEach((row, index) => {
+    if (!row || typeof row !== 'object' || Array.isArray(row)) throw new Error(`rows[${index}] must be object`)
+    for (const key of required) {
+      if (row[key] === undefined || row[key] === null || row[key] === '') throw new Error(`rows[${index}].${key} is required`)
+    }
+    for (const [key, propertySchema] of Object.entries(properties)) {
+      if (row[key] !== undefined && row[key] !== null) validateValue(row[key], propertySchema, `rows[${index}].${key}`)
+    }
+  })
+}
+
+export async function defineDataFormat({ project, dataset, schema, token = '', server = '' } = {}, deps = {}) {
+  if (!project) throw new Error('project is required')
+  if (!dataset) throw new Error('dataset is required')
+  if (!schema || typeof schema !== 'object' || schema.type !== 'object') throw new Error('schema must be a JSON object schema')
+  const homeDir = deps.homeDir || os.homedir()
+  const request = deps.requestJson || requestJson
+  const result = await request(`/api/projects/${slugify(project)}/data/formats`, {
+    method: 'POST',
+    body: { dataset: slugify(dataset), schema },
+    config: { token, server: server || 'https://app.11agents.ai' },
+  })
+  await mkdir(formatsDir(project, { homeDir }), { recursive: true })
+  await writeFile(schemaPath(project, dataset, { homeDir }), JSON.stringify({
+    dataset: slugify(dataset),
+    schema,
+    schema_revision: Number(result?.schema_revision || 1),
+    defined_at: new Date().toISOString(),
+  }, null, 2))
+  return result
+}
+
+async function readLockedFormat(project, dataset, { homeDir = os.homedir() } = {}) {
+  return JSON.parse(await readFile(schemaPath(project, dataset, { homeDir }), 'utf8'))
+}
+
+export async function pushDataRows({ project, dataset, date, rows, token = '', server = '' } = {}, deps = {}) {
+  if (!project) throw new Error('project is required')
+  if (!dataset) throw new Error('dataset is required')
+  if (!date) throw new Error('date is required')
+  const homeDir = deps.homeDir || os.homedir()
+  const locked = await readLockedFormat(project, dataset, { homeDir })
+  validateRowsAgainstSchema(rows, locked.schema)
+  const request = deps.requestJson || requestJson
+  return request(`/api/projects/${slugify(project)}/data/push`, {
+    method: 'POST',
+    body: {
+      dataset: slugify(dataset),
+      date,
+      schema_revision: locked.schema_revision,
+      rows,
+    },
+    config: { token, server: server || 'https://app.11agents.ai' },
+  })
+}

package/src/commands/database.js

@@ -0,0 +1,60 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { requestJson } from '../client.js'
+
+function slugify(value) {
+  return String(value || 'project')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'project'
+}
+
+export function buildDatabaseDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.11agents', slugify(project), 'database')
+}
+
+async function readState(project, { homeDir = os.homedir() } = {}) {
+  try {
+    return JSON.parse(await readFile(path.join(buildDatabaseDir(project, { homeDir }), 'sync-state.json'), 'utf8'))
+  } catch {
+    return {}
+  }
+}
+
+export async function syncDatabase({ project, mode = 'pull', token = '', server = '' } = {}, deps = {}) {
+  if (!project) throw new Error('database sync requires project')
+  const homeDir = deps.homeDir || os.homedir()
+  const request = deps.requestJson || requestJson
+  const dir = buildDatabaseDir(project, { homeDir })
+  const state = await readState(project, { homeDir })
+  const body = {
+    mode,
+    local_revision: Number(state.cloud_revision || 0),
+  }
+  if (mode === 'push') {
+    body.snapshot = JSON.parse(await readFile(path.join(dir, 'snapshot.json'), 'utf8'))
+  }
+  const result = await request(`/api/projects/${slugify(project)}/database/sync`, {
+    method: 'POST',
+    body,
+    config: { token, server: server || 'https://app.11agents.ai' },
+  })
+  await mkdir(dir, { recursive: true })
+  if (result?.snapshot !== undefined) {
+    await writeFile(path.join(dir, 'snapshot.json'), JSON.stringify(result.snapshot, null, 2))
+  }
+  await writeFile(path.join(dir, 'sync-state.json'), JSON.stringify({
+    cloud_revision: Number(result?.cloud_revision || 0),
+    synced_at: result?.synced_at || new Date().toISOString(),
+  }, null, 2))
+  return {
+    ok: true,
+    project: slugify(project),
+    mode,
+    path: dir,
+    cloud_revision: Number(result?.cloud_revision || 0),
+    synced_at: result?.synced_at || '',
+  }
+}

package/src/commands/knowledge.js

@@ -0,0 +1,213 @@
+import { mkdir, readFile, readdir, writeFile } from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+import { flag } from '../args.js'
+import { requestJson } from '../client.js'
+
+function slugify(value) {
+  return String(value || 'project')
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '') || 'project'
+}
+
+function safeLocalPath(value, id) {
+  const raw = String(value || '').trim()
+  if (raw && !raw.startsWith('/') && !raw.split('/').includes('..')) return raw
+  return `nodes/${slugify(id)}.md`
+}
+
+const MARKDOWN_NODE_KINDS = new Set(['document', 'fact', 'decision', 'insight', 'resource', 'task-context'])
+
+function normalizeSnapshot(snapshot = {}) {
+  return {
+    cloud_revision: Number(snapshot.cloud_revision || snapshot.knowledge_base?.cloud_revision || 0),
+    local_revision: String(snapshot.local_revision || ''),
+    nodes: Array.isArray(snapshot.nodes) ? snapshot.nodes.map((node, index) => {
+      const id = slugify(node.id || node.title || `node-${index + 1}`)
+      return {
+        id,
+        kind: String(node.kind || 'document'),
+        title: String(node.title || id),
+        body: String(node.body || ''),
+        local_path: safeLocalPath(node.local_path || node.localPath, id),
+        metadata: node.metadata && typeof node.metadata === 'object' ? node.metadata : {},
+      }
+    }).sort((a, b) => a.id.localeCompare(b.id)) : [],
+    edges: Array.isArray(snapshot.edges) ? snapshot.edges.map(edge => ({
+      from: slugify(edge.from || edge.from_node_id),
+      to: slugify(edge.to || edge.to_node_id),
+      relation: slugify(edge.relation || 'related'),
+      metadata: edge.metadata && typeof edge.metadata === 'object' ? edge.metadata : {},
+    })).filter(edge => edge.from && edge.to).sort((a, b) => (
+      `${a.from}:${a.to}:${a.relation}`.localeCompare(`${b.from}:${b.to}:${b.relation}`)
+    )) : [],
+  }
+}
+
+function markdownForNode(node) {
+  return [
+    `# ${node.title}`,
+    '',
+    `kind: ${node.kind}`,
+    `id: ${node.id}`,
+    '',
+    node.body || '',
+    '',
+  ].join('\n')
+}
+
+function bodyFromMarkdownNode(markdown, fallback = '') {
+  const lines = String(markdown || '').split('\n')
+  let index = 0
+  if (lines[index]?.startsWith('# ')) index += 1
+  if (lines[index] === '') index += 1
+  if (/^kind:\s*/.test(lines[index] || '')) index += 1
+  if (/^id:\s*/.test(lines[index] || '')) index += 1
+  if (lines[index] === '') index += 1
+  const body = lines.slice(index).join('\n').replace(/\n+$/, '')
+  return body || fallback
+}
+
+function isKnowledgeTextFile(name) {
+  return name.endsWith('.md') || name === 'llms.txt' || name === 'llms-full.txt'
+}
+
+async function listKnowledgeTextFiles(baseDir, currentDir = baseDir) {
+  const entries = await readdir(currentDir, { withFileTypes: true }).catch(() => [])
+  const files = []
+  for (const entry of entries) {
+    if (entry.name.startsWith('.')) continue
+    const fullPath = path.join(currentDir, entry.name)
+    if (entry.isDirectory()) {
+      files.push(...await listKnowledgeTextFiles(baseDir, fullPath))
+      continue
+    }
+    if (!entry.isFile() || !isKnowledgeTextFile(entry.name)) continue
+    files.push(path.relative(baseDir, fullPath).split(path.sep).join('/'))
+  }
+  return files.sort((a, b) => a.localeCompare(b))
+}
+
+function titleFromLocalPath(localPath) {
+  const basename = path.basename(localPath).replace(/\.(md|txt)$/i, '')
+  if (basename.toLowerCase() === 'readme') return 'README'
+  if (basename.toLowerCase() === 'claude') return 'Agent Instructions'
+  if (basename.toLowerCase() === 'index') return 'Knowledge Map'
+  return basename
+    .split(/[-_]+/)
+    .filter(Boolean)
+    .map(part => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`)
+    .join(' ') || localPath
+}
+
+function kindFromLocalPath(localPath) {
+  const folder = localPath.split('/').filter(Boolean)[0]
+  if (MARKDOWN_NODE_KINDS.has(folder)) return folder
+  if (folder === 'resources') return 'resource'
+  if (folder === 'decisions') return 'decision'
+  if (folder === 'insights') return 'insight'
+  if (folder === 'tasks') return 'task-context'
+  return 'document'
+}
+
+export function buildKnowledgeBaseDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.11agents', slugify(project), 'knowledge_base')
+}
+
+export async function writeKnowledgeSnapshot(project, snapshot, { homeDir = os.homedir() } = {}) {
+  const normalized = normalizeSnapshot(snapshot)
+  const baseDir = buildKnowledgeBaseDir(project, { homeDir })
+  const localRevision = normalized.local_revision || `${Date.now()}`
+  const index = {
+    cloud_revision: normalized.cloud_revision,
+    local_revision: localRevision,
+    nodes: normalized.nodes,
+    edges: normalized.edges,
+  }
+  await mkdir(path.join(baseDir, 'nodes'), { recursive: true })
+  await writeFile(path.join(baseDir, 'index.json'), JSON.stringify(index, null, 2))
+  await writeFile(path.join(baseDir, 'sync-state.json'), JSON.stringify({
+    cloud_revision: normalized.cloud_revision,
+    local_revision: localRevision,
+    synced_at: new Date().toISOString(),
+  }, null, 2))
+  for (const node of normalized.nodes) {
+    const target = path.join(baseDir, node.local_path)
+    await mkdir(path.dirname(target), { recursive: true })
+    await writeFile(target, markdownForNode(node))
+  }
+  return index
+}
+
+export async function readKnowledgeSnapshot(project, { homeDir = os.homedir() } = {}) {
+  const baseDir = buildKnowledgeBaseDir(project, { homeDir })
+  const raw = await readFile(path.join(baseDir, 'index.json'), 'utf-8').catch(() => '{}')
+  const snapshot = normalizeSnapshot(JSON.parse(raw))
+  const nodesByPath = new Map(snapshot.nodes.map(node => [node.local_path, node]))
+  for (const localPath of await listKnowledgeTextFiles(baseDir)) {
+    if (nodesByPath.has(localPath)) continue
+    nodesByPath.set(localPath, {
+      id: slugify(localPath.replace(/\.(md|txt)$/i, '')),
+      kind: kindFromLocalPath(localPath),
+      title: titleFromLocalPath(localPath),
+      body: '',
+      local_path: localPath,
+      metadata: { source: 'local-markdown' },
+    })
+  }
+  const nodes = await Promise.all([...nodesByPath.values()].map(async node => {
+    const markdown = await readFile(path.join(baseDir, node.local_path), 'utf-8').catch(() => null)
+    if (markdown === null) return node
+    return { ...node, body: bodyFromMarkdownNode(markdown, node.body) }
+  }))
+  return { ...snapshot, nodes: nodes.sort((a, b) => a.id.localeCompare(b.id)) }
+}
+
+export async function syncKnowledge(flags = {}, deps = {}) {
+  const project = flag(flags, 'project', flag(flags, 'workspace', process.env.GTM_SWARM_WORKSPACE || ''))
+  if (!project) throw new Error('knowledge sync requires --project <slug>')
+  const mode = flag(flags, 'mode', flags.push ? 'push' : 'pull')
+  const request = deps.requestJson || requestJson
+  const log = deps.log || (value => console.log(value))
+  const homeDir = deps.homeDir || os.homedir()
+  const localSnapshot = await readKnowledgeSnapshot(project, { homeDir })
+  const body = mode === 'push'
+    ? { ...localSnapshot, mode: 'push', actor: 'cli' }
+    : { mode: 'pull', local_revision: localSnapshot.local_revision, cloud_revision: localSnapshot.cloud_revision, actor: 'cli' }
+  const result = await request(`/api/projects/${project}/knowledge/sync`, {
+    method: 'POST',
+    body,
+  })
+  const written = await writeKnowledgeSnapshot(project, result, { homeDir })
+  const payload = {
+    ok: true,
+    project,
+    mode,
+    path: buildKnowledgeBaseDir(project, { homeDir }),
+    cloud_revision: written.cloud_revision,
+    local_revision: written.local_revision,
+    nodes: written.nodes.length,
+    edges: written.edges.length,
+  }
+  log(JSON.stringify(payload, null, 2))
+  return { ...written, path: payload.path }
+}
+
+export async function knowledgeStatus(flags = {}, deps = {}) {
+  const project = flag(flags, 'project', flag(flags, 'workspace', process.env.GTM_SWARM_WORKSPACE || ''))
+  if (!project) throw new Error('knowledge status requires --project <slug>')
+  const homeDir = deps.homeDir || os.homedir()
+  const snapshot = await readKnowledgeSnapshot(project, { homeDir })
+  const payload = {
+    project,
+    path: buildKnowledgeBaseDir(project, { homeDir }),
+    cloud_revision: snapshot.cloud_revision,
+    local_revision: snapshot.local_revision,
+    nodes: snapshot.nodes.length,
+    edges: snapshot.edges.length,
+  }
+  ;(deps.log || (value => console.log(value)))(JSON.stringify(payload, null, 2))
+  return payload
+}

package/src/commands/push.js

@@ -6,6 +6,7 @@ import { buildTelemetryBatch, validateTelemetryBatch } from '../schema.js'
 function defaults(flags) {
   return {
     workspace: flag(flags, 'workspace', process.env.GTM_SWARM_WORKSPACE || ''),
+    agent_id: flag(flags, 'agent-id', process.env.GTM_SWARM_AGENT_ID || ''),
     agent_key: flag(flags, 'agent', process.env.GTM_SWARM_AGENT || ''),
     node_id: flag(flags, 'node', process.env.GTM_SWARM_NODE || 'local'),
   }

package/src/commands/runtime.js

@@ -1,11 +1,17 @@
 import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
+import { appendFile, mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import os from 'node:os'
 import { dirname, resolve } from 'node:path'
+import path from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { fileURLToPath } from 'node:url'
 import { flag } from '../args.js'
 import { getControlConfig, requestJson } from '../client.js'
+import { syncKnowledge } from './knowledge.js'
 import { buildRuntimeScan } from '../runtime-scan.js'
+import { handleMcpRequest } from '../mcp.js'
 
 const CLI_VERSION = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json'), 'utf-8')).version
 
@@ -55,10 +61,13 @@ function runtimeDeps(overrides = {}) {
     buildRuntimeScan: overrides.buildRuntimeScan || buildRuntimeScan,
     importHandler: overrides.importHandler || (async handlerPath => import(pathToFileURL(resolve(handlerPath)).href)),
     log: overrides.log || (value => console.log(value)),
+    homeDir: overrides.homeDir || os.homedir(),
     runCodex: overrides.runCodex || runCodex,
     runProcess: overrides.runProcess || runProcess,
     requestJson: overrides.requestJson || requestJson,
     sleep: overrides.sleep || sleep,
+    syncKnowledge: overrides.syncKnowledge || syncKnowledge,
+    mcpKnowledgeSync: overrides.mcpKnowledgeSync || mcpKnowledgeSync,
   }
 }
 
@@ -140,6 +149,37 @@ export async function heartbeatRuntime(flags = {}, deps = {}) {
   return result
 }
 
+export async function syncRuntimeProjectMetadata(flags = {}, deps = {}) {
+  const { log, requestJson: request, homeDir } = runtimeDeps(deps)
+  const config = configFromFlags(flags)
+  if (!config.token) throw new Error('GTM_WRITES_TOKEN or --token is required')
+
+  const result = await request('/api/runtime/projects', {
+    method: 'GET',
+    config,
+  })
+  const materialized = await materializeRuntimeProjectDirectories(result?.projects || [], { homeDir })
+  log(JSON.stringify({
+    ok: true,
+    synced: 'runtime projects',
+    base_dir: materialized.base_dir,
+    projects: materialized.projects,
+  }, null, 2))
+  return { ...result, ...materialized }
+}
+
+async function syncRuntimeProjectMetadataBestEffort(flags, deps) {
+  try {
+    return await syncRuntimeProjectMetadata(flags, deps)
+  } catch (error) {
+    deps.log(JSON.stringify({
+      warning: 'runtime project metadata sync failed',
+      error: errorMessage(error),
+    }, null, 2))
+    return null
+  }
+}
+
 function normalizeTaskCompletion(task, completion) {
   const result = completion && typeof completion === 'object' ? completion : {}
   return {
@@ -165,10 +205,315 @@ function compactJson(value) {
   return JSON.stringify(value ?? null, null, 2)
 }
 
+async function mcpKnowledgeSync(flags = {}, deps = {}) {
+  const result = await handleMcpRequest({
+    method: 'tools/call',
+    params: {
+      name: 'knowledge_sync',
+      arguments: {
+        project: flags.project,
+        mode: flags.mode,
+        server: flags.server,
+        token: flags.token,
+      },
+    },
+  }, deps)
+  return JSON.parse(result.content?.[0]?.text || '{}')
+}
+
+const nonAlphaNum = /[^a-z0-9]+/g
+
+function slugify(value, fallback = 'project') {
+  return String(value || fallback)
+    .trim()
+    .toLowerCase()
+    .replace(nonAlphaNum, '-')
+    .replace(/^-|-$/g, '') || fallback
+}
+
+function sanitizeTaskId(value) {
+  return slugify(value, 'task')
+}
+
+export function buildRuntimeProjectDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.11agents', slugify(project))
+}
+
+export function buildRuntimeKnowledgeDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(buildRuntimeProjectDir(project, { homeDir }), 'knowledge_base')
+}
+
+export function buildRuntimeAgentMemoryDir(project, agent, { homeDir = os.homedir() } = {}) {
+  return path.join(buildRuntimeProjectDir(project, { homeDir }), 'agents', slugify(agent, 'agent'), 'memory')
+}
+
+export function buildRuntimeAgentSkillsDir(project, agent, { homeDir = os.homedir() } = {}) {
+  return path.join(buildRuntimeProjectDir(project, { homeDir }), 'agents', slugify(agent, 'agent'), 'skills')
+}
+
+function projectSlugForTask(task, flags = {}) {
+  return slugify(task.workspace?.slug || task.workspace_slug || flag(flags, 'project') || flag(flags, 'workspace') || 'project')
+}
+
+function projectDirForTask(task, flags = {}, deps) {
+  return buildRuntimeProjectDir(projectSlugForTask(task, flags), { homeDir: deps.homeDir })
+}
+
+async function writeFileIfMissing(filePath, content) {
+  try {
+    await writeFile(filePath, content, { flag: 'wx' })
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error
+  }
+}
+
+function defaultMemoryQmd(project, agent) {
+  return [
+    `# ${agent.name || agent.id || 'Agent'} Memory`,
+    '',
+    `project: ${project.slug || project.name || 'project'}`,
+    `agent: ${agent.name || agent.id || 'agent'}`,
+    '',
+  ].join('\n')
+}
+
+function safeQmdName(value, fallback) {
+  const name = slugify(String(value || '').replace(/\.qmd$/i, ''), fallback)
+  return `${name}.qmd`
+}
+
+export async function materializeRuntimeProjectDirectories(projects = [], { homeDir = os.homedir() } = {}) {
+  const baseDir = path.join(homeDir, '.11agents')
+  await mkdir(baseDir, { recursive: true })
+  const written = []
+  for (const project of Array.isArray(projects) ? projects : []) {
+    const projectSlug = slugify(project?.slug || project?.name, 'project')
+    const projectDir = buildRuntimeProjectDir(projectSlug, { homeDir })
+    await mkdir(buildRuntimeKnowledgeDir(projectSlug, { homeDir }), { recursive: true })
+    written.push(projectDir)
+    for (const agent of Array.isArray(project?.agents) ? project.agents : []) {
+      const agentName = agent?.name || agent?.id || 'agent'
+      const memoryDir = buildRuntimeAgentMemoryDir(projectSlug, agentName, { homeDir })
+      const skillsDir = buildRuntimeAgentSkillsDir(projectSlug, agentName, { homeDir })
+      await mkdir(memoryDir, { recursive: true })
+      await mkdir(skillsDir, { recursive: true })
+      await writeFileIfMissing(path.join(memoryDir, 'index.qmd'), defaultMemoryQmd({ ...project, slug: projectSlug }, agent))
+      for (const memory of Array.isArray(agent?.memory) ? agent.memory : []) {
+        await writeFileIfMissing(path.join(memoryDir, safeQmdName(memory, 'memory')), '')
+      }
+      for (const skill of Array.isArray(agent?.skills) ? agent.skills : []) {
+        await mkdir(path.join(skillsDir, slugify(skill?.name || skill, 'skill')), { recursive: true })
+      }
+    }
+  }
+  return { base_dir: baseDir, projects: written.length }
+}
+
+function knowledgeDeepOrganizeSpec(task) {
+  if (task.queue_event?.trigger_type !== 'knowledge_deep_organize') return null
+  const raw = String(task.queue_event?.trigger_summary || '')
+  try {
+    const parsed = JSON.parse(raw)
+    return {
+      source_url: String(parsed.source_url || parsed.url || ''),
+      source_type: String(parsed.source_type || '').toLowerCase(),
+    }
+  } catch {
+    return { source_url: raw, source_type: raw.includes('github.com') ? 'github' : 'url' }
+  }
+}
+
+async function readJsonFile(filePath, fallback = {}) {
+  try {
+    return JSON.parse(await readFile(filePath, 'utf8'))
+  } catch (error) {
+    if (error?.code === 'ENOENT') return fallback
+    return fallback
+  }
+}
+
+function stableHash(value) {
+  return createHash('sha256').update(JSON.stringify(value ?? null)).digest('hex')
+}
+
+function assertSafeRelativePath(filePath) {
+  const clean = path.normalize(String(filePath || ''))
+  if (!clean || path.isAbsolute(clean) || clean === '..' || clean.startsWith(`..${path.sep}`)) {
+    throw new Error(`invalid skill file path: ${filePath}`)
+  }
+  return clean
+}
+
+function decodeFileContent(file) {
+  if (file?.encoding === 'base64') return Buffer.from(String(file.content || ''), 'base64')
+  return Buffer.from(String(file?.content || ''), 'utf8')
+}
+
+function agentNameForTask(task) {
+  return task.agent?.name || task.agent?.id || task.agent_id || task.assignee_id || 'agent'
+}
+
+function normalizeSkillBundle(skill = {}) {
+  return {
+    id: String(skill.id || ''),
+    name: String(skill.name || 'skill'),
+    content: String(skill.content || ''),
+    files: Array.isArray(skill.files)
+      ? skill.files.map(file => ({
+        path: String(file.path || ''),
+        encoding: file.encoding === 'base64' ? 'base64' : 'utf8',
+        content: String(file.content || ''),
+      })).sort((a, b) => a.path.localeCompare(b.path))
+      : [],
+  }
+}
+
+async function materializeSkillsIfChanged({ task, workdir, flags, deps }) {
+  const skills = Array.isArray(task.agent?.skills) ? task.agent.skills.map(normalizeSkillBundle) : []
+  if (!skills.length) return { changed: false, count: 0 }
+
+  const skillsDir = path.join(workdir, 'agents', slugify(agentNameForTask(task), 'agent'), 'skills')
+  const statePath = path.join(skillsDir, 'skills-state.json')
+  const nextHash = stableHash(skills)
+  const current = await readJsonFile(statePath, {})
+  if (current.hash === nextHash) return { changed: false, count: skills.length }
+
+  await mkdir(skillsDir, { recursive: true })
+  for (const skill of skills) {
+    const skillDir = path.join(skillsDir, slugify(skill.name, 'skill'))
+    await mkdir(skillDir, { recursive: true })
+    await writeFile(path.join(skillDir, 'SKILL.md'), skill.content, 'utf8')
+    for (const file of skill.files) {
+      const relativePath = assertSafeRelativePath(file.path)
+      const target = path.join(skillDir, relativePath)
+      await mkdir(path.dirname(target), { recursive: true })
+      await writeFile(target, decodeFileContent(file))
+    }
+  }
+  await writeFile(statePath, JSON.stringify({
+    hash: nextHash,
+    count: skills.length,
+    skills_dir: skillsDir,
+    synced_at: new Date().toISOString(),
+  }, null, 2))
+  return { changed: true, count: skills.length, skills_dir: skillsDir }
+}
+
+async function appendTaskMemoryDelta({ task, completion, workdir }) {
+  const memoryDelta = String(completion?.memory_delta || completion?.memoryDelta || '').trim()
+  if (!memoryDelta) return { written: false }
+  const memoryDir = path.join(workdir, 'agents', slugify(agentNameForTask(task), 'agent'), 'memory')
+  await mkdir(memoryDir, { recursive: true })
+  const indexPath = path.join(memoryDir, 'index.qmd')
+  await writeFileIfMissing(indexPath, defaultMemoryQmd({ slug: projectSlugForTask(task), name: task.workspace?.name }, task.agent || {}))
+  await appendFile(indexPath, [
+    '',
+    `## ${new Date().toISOString()} ${task.id || ''}`.trim(),
+    '',
+    memoryDelta,
+    '',
+  ].join('\n'))
+  return { written: true, path: indexPath }
+}
+
+function databaseSyncSpec(task) {
+  const spec = task.database || task.cloud_database || task.workspace?.database || null
+  if (!spec || typeof spec !== 'object') return null
+  const cloudRevision = Number(spec.cloud_revision ?? spec.cloudRevision ?? spec.revision ?? 0)
+  const syncRequired = spec.sync_required === true || spec.syncRequired === true
+  if (!syncRequired && !cloudRevision) return null
+  return { cloudRevision, syncRequired }
+}
+
+async function syncDatabaseIfNeeded({ task, workdir, config, deps }) {
+  const spec = databaseSyncSpec(task)
+  if (!spec) return { synced: false }
+  const statePath = path.join(workdir, 'database', 'sync-state.json')
+  const current = await readJsonFile(statePath, {})
+  const localRevision = Number(current.cloud_revision || 0)
+  if (!spec.syncRequired && localRevision === spec.cloudRevision) return { synced: false, cloud_revision: localRevision }
+
+  const project = projectSlugForTask(task)
+  const result = await deps.requestJson(`/api/projects/${project}/database/sync`, {
+    method: 'POST',
+    body: {
+      task_id: task.id,
+      local_revision: localRevision,
+      cloud_revision: spec.cloudRevision,
+    },
+    config,
+  })
+  await mkdir(path.dirname(statePath), { recursive: true })
+  if (result?.snapshot !== undefined) {
+    await writeFile(path.join(path.dirname(statePath), 'snapshot.json'), JSON.stringify(result.snapshot, null, 2))
+  }
+  await writeFile(statePath, JSON.stringify({
+    cloud_revision: Number(result?.cloud_revision ?? spec.cloudRevision),
+    synced_at: result?.synced_at || new Date().toISOString(),
+  }, null, 2))
+  return { synced: true, cloud_revision: Number(result?.cloud_revision ?? spec.cloudRevision) }
+}
+
+function agentEnvironment(task) {
+  const values = task.agent?.environment_variables || task.agent?.environment || task.agent?.custom_env || {}
+  const env = {}
+  if (Array.isArray(values)) {
+    for (const item of values) {
+      const key = String(item?.key || '').trim()
+      if (key) env[key] = String(item?.value || '')
+    }
+    return env
+  }
+  if (values && typeof values === 'object') {
+    for (const [key, value] of Object.entries(values)) {
+      const cleanKey = String(key || '').trim()
+      if (cleanKey) env[cleanKey] = String(value ?? '')
+    }
+  }
+  return env
+}
+
+async function prepareRuntimeTask(task, flags, deps, config) {
+  const workdir = flag(flags, 'codex-workdir') || projectDirForTask(task, flags, deps)
+  const tmpDir = path.join(workdir, 'tmp', sanitizeTaskId(task.id))
+  await mkdir(tmpDir, { recursive: true })
+
+  const database = await syncDatabaseIfNeeded({ task, workdir, config, deps })
+  const skills = await materializeSkillsIfChanged({ task, workdir, flags, deps })
+  const env = {
+    ...process.env,
+    ...agentEnvironment(task),
+    ELEVENAGENTS_PROJECT_DIR: workdir,
+    ELEVENAGENTS_TASK_TMP: tmpDir,
+    ELEVENAGENTS_TASK_ID: String(task.id || ''),
+  }
+
+  return {
+    workdir,
+    tmp_dir: tmpDir,
+    project_slug: projectSlugForTask(task, flags),
+    readonly: true,
+    env,
+    database,
+    skills,
+  }
+}
+
 function buildCodexPrompt(task) {
+  const deepOrganize = knowledgeDeepOrganizeSpec(task)
   return [
     'You are executing an 11agents task as the assigned agent.',
     '',
+    'Execution workspace:',
+    compactJson({
+      workdir: task.execution_context?.workdir,
+      tmp_dir: task.execution_context?.tmp_dir,
+      project_slug: task.execution_context?.project_slug,
+      knowledge_base: './knowledge_base/',
+      rule: 'Treat the project directory as read-only project context except ./knowledge_base/ for durable project knowledge updates and ./tmp/<taskId>/ for temporary scratch files.',
+      cleanup: 'Temporary files under ./tmp/<taskId>/ are removed by the CLI after the task finishes.',
+    }),
+    '',
     'Task context:',
     compactJson({
       queue_event: task.queue_event,
@@ -176,6 +521,7 @@ function buildCodexPrompt(task) {
       issue: task.issue,
       trigger_summary: task.trigger_summary,
       thread_memory: task.thread_memory,
+      project_knowledge: task.project_knowledge,
     }),
     '',
     'Assigned agent context:',
@@ -192,6 +538,33 @@ function buildCodexPrompt(task) {
     '',
     'Thread comments:',
     compactJson(task.comments || []),
+    deepOrganize ? [
+      '',
+      'Knowledge deep organization task:',
+      compactJson({
+        trigger_type: 'knowledge_deep_organize',
+        source_url: deepOrganize.source_url,
+        source_type: deepOrganize.source_type || (deepOrganize.source_url.includes('github.com') ? 'github' : 'url'),
+        output_dir: task.execution_context?.workdir ? `${task.execution_context.workdir}/knowledge_base` : './knowledge_base',
+        callback: 'After organizing files, call the 11agents MCP knowledge_sync tool with mode=push so cloud receives the finished wiki.',
+      }),
+      '',
+      'Build the knowledge base using the standard llms.txt / LLM Wiki pattern popularized for LLM-readable documentation:',
+      '- Create or update ./knowledge_base/llms.txt with one H1 project title, a blockquote summary, concise context, and H2 sections containing Markdown links to the most important files.',
+      '- Create or update ./knowledge_base/llms-full.txt as a fuller single-file context pack when useful.',
+      '- Create or update ./knowledge_base/README.md, ./knowledge_base/index.md, and ./knowledge_base/CLAUDE.md as the human entry point, node map, and agent operating guide.',
+      '- Treat the finished result as an agent skill graph like a strong hand-built knowledge base: every durable file should tell the next agent exactly when to read it and how to act on it.',
+      '- Do not stop at project-profile.md / knowledge-map.md placeholders. Create concrete markdown files with actionable content.',
+      '- For product, website, or business sources, use semantic folders such as information/, voice/, audience/, marketing/, product-design/, resources/, and decisions/. Create files like information/what-we-do/product-overview.md, voice/brand-voice.md, audience/README.md, and marketing/README.md when the source supports them.',
+      '- For GitHub sources, use semantic folders such as codebase/, architecture/, api/, operations/, examples/, resources/, and agent-playbook/. Create files like codebase/README.md, architecture/overview.md, operations/setup.md, api/README.md, and examples/README.md when the repo supports them.',
+      '- README.md should include a "Where to Start" table and a directory overview.',
+      '- index.md should include Identity, Node Map, and Execution Instructions sections with wiki-style references to important files.',
+      '- CLAUDE.md should include the exact read order and output/update rules for runtime agents.',
+      '- If source_type is github, inspect README, docs, package manifests, examples, and source tree. Prefer concise durable explanations over raw dumps.',
+      '- If source_type is url, read the page and prefer /llms.txt or /llms-full.txt from that origin when available.',
+      '- Keep file paths stable and descriptive. Do not write temporary research into the durable wiki.',
+      '- When done, use MCP to push the local knowledge_base back to cloud.',
+    ].join('\n') : '',
     '',
     'Work in this repository and make the needed changes. When finished, respond with a concise summary for the task thread.',
   ].join('\n')
@@ -199,7 +572,7 @@ function buildCodexPrompt(task) {
 
 async function runCodex({ task, prompt, flags = {}, deps }) {
   const codexBin = flag(flags, 'codex-bin', 'codex')
-  const workdir = flag(flags, 'codex-workdir', process.cwd())
+  const workdir = flag(flags, 'codex-workdir', task.execution_context?.workdir || process.cwd())
   const args = [
     '--ask-for-approval',
     'never',
@@ -219,7 +592,7 @@ async function runCodex({ task, prompt, flags = {}, deps }) {
 
   const commandLine = [codexBin, ...args].map(value => JSON.stringify(String(value))).join(' ')
   deps.log(JSON.stringify({ running: 'codex exec', command: commandLine, workdir }, null, 2))
-  const result = await deps.runProcess(codexBin, args, { input: prompt, cwd: workdir })
+  const result = await deps.runProcess(codexBin, args, { input: prompt, cwd: workdir, env: task.execution_context?.env || process.env })
   const output = String(result.stdout || '').trim()
   const error = String(result.stderr || '').trim()
   if (result.code !== 0) {
@@ -289,6 +662,21 @@ async function claimAndRunRuntimeTasks(registration, flags, deps, handlerModule,
     }
 
     deps.log(JSON.stringify({ claimed: runtimeTask.id, runtime_id: runtime.id }, null, 2))
+    if (runtimeTask.workspace?.slug) {
+      await runWithDaemonRetry('sync knowledge base', () => (
+        deps.syncKnowledge({
+          project: runtimeTask.workspace.slug,
+          mode: 'pull',
+          server: flags.server,
+          token: flags.token,
+        }, {
+          requestJson: (apiPath, options = {}) => deps.requestJson(apiPath, { ...options, config }),
+          log: () => {},
+        })
+      ), deps, retryState)
+    }
+    const executionContext = await prepareRuntimeTask(runtimeTask, flags, deps, config)
+    runtimeTask.execution_context = executionContext
     let completion
     try {
       completion = await handlerModule.handleRuntimeTask(runtimeTask)
@@ -297,6 +685,24 @@ async function claimAndRunRuntimeTasks(registration, flags, deps, handlerModule,
         comment: error instanceof Error ? error.message : String(error),
         status: 'failed',
       }
+    } finally {
+      await rm(executionContext.tmp_dir, { recursive: true, force: true })
+    }
+    await appendTaskMemoryDelta({ task: runtimeTask, completion, workdir: executionContext.workdir })
+
+    if (runtimeTask.workspace?.slug) {
+      const syncBack = knowledgeDeepOrganizeSpec(runtimeTask) ? deps.mcpKnowledgeSync : deps.syncKnowledge
+      await runWithDaemonRetry('sync knowledge base back to cloud', () => (
+        syncBack({
+          project: runtimeTask.workspace.slug,
+          mode: 'push',
+          server: flags.server,
+          token: flags.token,
+        }, {
+          requestJson: (apiPath, options = {}) => deps.requestJson(apiPath, { ...options, config }),
+          log: () => {},
+        })
+      ), deps, retryState)
     }
 
     const body = normalizeTaskCompletion(runtimeTask, completion)
@@ -319,6 +725,7 @@ export async function startRuntimeDaemon(flags = {}, deps = {}) {
   const heartbeatIntervalMs = Number(flag(flags, 'heartbeat-interval', '15')) * 1000
   const scanIntervalMs = Number(flag(flags, 'scan-interval', '60')) * 1000
   const taskIntervalMs = Number(flag(flags, 'task-interval', flag(flags, 'heartbeat-interval', '15'))) * 1000
+  const projectRefreshIntervalMs = Number(flag(flags, 'project-refresh-interval', '1800')) * 1000
   const once = Boolean(flags.once)
   const handlerPath = flag(flags, 'handler')
 
@@ -331,18 +738,23 @@ export async function startRuntimeDaemon(flags = {}, deps = {}) {
   if (!Number.isFinite(taskIntervalMs) || taskIntervalMs <= 0) {
     throw new Error('--task-interval must be a positive number of seconds')
   }
+  if (!Number.isFinite(projectRefreshIntervalMs) || projectRefreshIntervalMs <= 0) {
+    throw new Error('--project-refresh-interval must be a positive number of seconds')
+  }
 
   const handlerModule = await loadTaskHandler(handlerPath, resolvedDeps) || defaultTaskHandler(flags, resolvedDeps)
   const retryState = createRetryState()
   let registration = await runWithDaemonRetry('register runtime', () => registerRuntime(flags, resolvedDeps), resolvedDeps, retryState)
+  await syncRuntimeProjectMetadataBestEffort(flags, resolvedDeps)
   await claimAndRunRuntimeTasks(registration, flags, resolvedDeps, handlerModule, retryState)
   if (once) return
 
   let lastScan = Date.now()
   let lastHeartbeat = Date.now()
   let lastTaskPoll = Date.now()
+  let lastProjectRefresh = Date.now()
   while (true) {
-    await resolvedDeps.sleep(Math.min(heartbeatIntervalMs, taskIntervalMs))
+    await resolvedDeps.sleep(Math.min(heartbeatIntervalMs, taskIntervalMs, projectRefreshIntervalMs))
     const now = Date.now()
     if (now - lastScan >= scanIntervalMs) {
       registration = await runWithDaemonRetry('register runtime', () => registerRuntime(flags, resolvedDeps), resolvedDeps, retryState)
@@ -356,5 +768,9 @@ export async function startRuntimeDaemon(flags = {}, deps = {}) {
       await claimAndRunRuntimeTasks(registration, flags, resolvedDeps, handlerModule, retryState)
       lastTaskPoll = now
     }
+    if (now - lastProjectRefresh >= projectRefreshIntervalMs) {
+      await syncRuntimeProjectMetadataBestEffort(flags, resolvedDeps)
+      lastProjectRefresh = now
+    }
   }
 }

package/src/mcp.js

@@ -0,0 +1,100 @@
+import { syncKnowledge } from './commands/knowledge.js'
+import { requestJson } from './client.js'
+
+const TOOLS = [
+  {
+    name: 'knowledge_sync',
+    description: 'Pull cloud project knowledge to local disk or push local project knowledge back to cloud with a project token.',
+    inputSchema: {
+      type: 'object',
+      required: ['project', 'mode'],
+      properties: {
+        project: { type: 'string' },
+        mode: { type: 'string', enum: ['pull', 'push'] },
+        token: { type: 'string' },
+        server: { type: 'string' },
+      },
+    },
+  },
+]
+
+function textResult(value) {
+  return {
+    content: [{
+      type: 'text',
+      text: JSON.stringify(value, null, 2),
+    }],
+  }
+}
+
+function toolArgs(request) {
+  return request?.params?.arguments || {}
+}
+
+export async function handleMcpRequest(request, deps = {}) {
+  if (request.method === 'initialize') {
+    return {
+      protocolVersion: '2024-11-05',
+      capabilities: { tools: {} },
+      serverInfo: { name: '11agents-project-sync', version: '0.1.0' },
+    }
+  }
+  if (request.method === 'tools/list') return { tools: TOOLS }
+  if (request.method !== 'tools/call') throw new Error(`unsupported MCP method: ${request.method}`)
+
+  const name = request?.params?.name
+  const args = toolArgs(request)
+  if (name === 'knowledge_sync') {
+    const result = await syncKnowledge({
+      project: args.project,
+      mode: args.mode,
+      server: args.server,
+      token: args.token,
+    }, {
+      ...deps,
+      requestJson: (apiPath, options = {}) => (deps.requestJson || requestJson)(apiPath, {
+        ...options,
+        config: { token: args.token || '', server: args.server || 'https://app.11agents.ai' },
+      }),
+    })
+    return textResult(result)
+  }
+  throw new Error(`unknown MCP tool: ${name}`)
+}
+
+function jsonRpcError(id, error) {
+  return {
+    jsonrpc: '2.0',
+    id,
+    error: {
+      code: -32000,
+      message: error instanceof Error ? error.message : String(error),
+    },
+  }
+}
+
+export async function startMcpServer({ input = process.stdin, output = process.stdout, deps = {} } = {}) {
+  input.setEncoding('utf8')
+  let buffer = ''
+  input.on('data', chunk => {
+    buffer += chunk
+    let index = buffer.indexOf('\n')
+    while (index >= 0) {
+      const line = buffer.slice(0, index).trim()
+      buffer = buffer.slice(index + 1)
+      index = buffer.indexOf('\n')
+      if (!line) continue
+      ;(async () => {
+        let request
+        try {
+          request = JSON.parse(line)
+          if (!request.id && request.method === 'notifications/initialized') return
+          const result = await handleMcpRequest(request, deps)
+          output.write(`${JSON.stringify({ jsonrpc: '2.0', id: request.id, result })}\n`)
+        } catch (error) {
+          output.write(`${JSON.stringify(jsonRpcError(request?.id || null, error))}\n`)
+        }
+      })()
+    }
+  })
+}

package/src/schema.js

@@ -19,6 +19,8 @@ function fail(error) {
 export function validateTelemetryBatch(input) {
   if (!isObject(input)) return fail('batch must be an object')
   if (input.schema_version !== TELEMETRY_SCHEMA_VERSION) return fail(`schema_version must be ${TELEMETRY_SCHEMA_VERSION}`)
+  const agentId = input.agent_id ?? input.agentId
+  if (!isNonEmptyString(agentId)) return fail('agent_id is required')
   for (const field of ['workspace', 'agent_key', 'node_id']) {
     if (!isNonEmptyString(input[field])) return fail(`${field} is required`)
   }
@@ -43,13 +45,14 @@ export function validateTelemetryBatch(input) {
       if (typeof value !== 'number' || !Number.isFinite(value)) return fail(`observations[${i}].metrics.${key} must be a finite number`)
     }
   }
-  return { ok: true, batch: input }
+  return { ok: true, batch: { ...input, agent_id: agentId.trim() } }
 }
 
-export function buildTelemetryBatch({ workspace, agent_key, node_id, artifacts = [], observations = [] }) {
+export function buildTelemetryBatch({ workspace, agent_id, agent_key, node_id, artifacts = [], observations = [] }) {
   return {
     schema_version: TELEMETRY_SCHEMA_VERSION,
     workspace,
+    agent_id,
     agent_key,
     node_id,
     sent_at: new Date().toISOString(),