@11agents/cli 0.1.2 → 0.1.3

package/README.md

@@ -64,6 +64,15 @@ Useful daemon options:
 11agents daemon start --handler ./worker.js
 ```
 
+Before a claimed task is handed to the built-in Codex worker, the daemon prepares a local read-only project cache:
+
+- Cloud database snapshot: `~/.11agents/projects/<project>/database/snapshot.json`
+- Project knowledge base: `~/.11agents/projects/<project>/knowledge_base/`
+- Skill sync state: `~/.11agents/projects/<project>/skills-state.json`
+- Task scratch directory: `~/.11agents/projects/<project>/tmp/<taskId>/`
+
+Codex runs from `~/.11agents/projects/<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

package/bin/11agents.js

@@ -2,6 +2,7 @@
 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'
@@ -25,6 +26,8 @@ Usage:
   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 +35,12 @@ 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:
+  Built-in Codex tasks run from ~/.11agents/projects/<project>/ by default.
+  That directory is read-only project context. Temporary writes belong under
+  ./tmp/<taskId>/ and are cleaned by the daemon after the task finishes.`)
 }
 
 async function main() {
@@ -123,6 +131,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.3",
   "description": "11agents local runtime and telemetry CLI",
   "type": "module",
   "bin": {

package/src/commands/knowledge.js

@@ -0,0 +1,157 @@
+import { mkdir, readFile, 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`
+}
+
+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
+}
+
+export function buildKnowledgeBaseDir(project, { homeDir = os.homedir() } = {}) {
+  return path.join(homeDir, '.11agents', 'projects', 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 nodes = await Promise.all(snapshot.nodes.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 }
+}
+
+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,10 +1,15 @@
 import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
 import { readFileSync } from 'node:fs'
+import { 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'
 
 const CLI_VERSION = JSON.parse(readFileSync(resolve(dirname(fileURLToPath(import.meta.url)), '../../package.json'), 'utf-8')).version
@@ -55,10 +60,12 @@ 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,
   }
 }
 
@@ -165,10 +172,211 @@ function compactJson(value) {
   return JSON.stringify(value ?? null, null, 2)
 }
 
+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')
+}
+
+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 path.join(deps.homeDir, '.11agents', 'projects', projectSlugForTask(task, flags))
+}
+
+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 skillDirForProvider({ workdir, provider, codexHome }) {
+  if (provider === 'codex') return path.join(codexHome || path.join(os.homedir(), '.codex'), 'skills')
+  if (provider === 'claude') return path.join(workdir, '.claude', 'skills')
+  if (provider === 'copilot') return path.join(workdir, '.github', 'skills')
+  if (provider === 'opencode') return path.join(workdir, '.opencode', 'skills')
+  if (provider === 'cursor') return path.join(workdir, '.cursor', 'skills')
+  return path.join(workdir, '.agent_context', 'skills')
+}
+
+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 statePath = path.join(workdir, 'skills-state.json')
+  const nextHash = stableHash(skills)
+  const current = await readJsonFile(statePath, {})
+  if (current.hash === nextHash) return { changed: false, count: skills.length }
+
+  const provider = task.runtime?.provider || ''
+  const skillsDir = skillDirForProvider({
+    workdir,
+    provider,
+    codexHome: flag(flags, 'codex-home', process.env.CODEX_HOME || path.join(deps.homeDir, '.codex')),
+  })
+  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 }
+}
+
+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) {
   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 +384,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:',
@@ -199,7 +408,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 +428,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 +498,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 +521,22 @@ 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 })
+    }
+
+    if (runtimeTask.workspace?.slug) {
+      await runWithDaemonRetry('sync knowledge base back to cloud', () => (
+        deps.syncKnowledge({
+          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)

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(),