nemoris 0.1.0

package/src/onboarding/templates.js

@@ -0,0 +1,794 @@
+/**
+ * Bundled TOML and markdown templates for the onboarding scaffold phase.
+ * Each function accepts injected values and returns file content as a string.
+ */
+
+import path from "node:path";
+import { writeFile as writeFileAsync, mkdir as mkdirAsync, access as accessAsync } from "node:fs/promises";
+
+// ── Agent manifest ───────────────────────────────────────────────────────────
+
+/**
+ * Generates config/agents/{agentId}.toml
+ * Must satisfy AGENT_SCHEMA: id, primaryLane, memoryPolicy, toolPolicy
+ */
+export function agentTemplate({ agentId, installDir = "", workspaceRoot = "" }) {
+  // Normalise to forward slashes — backslashes break TOML string parsing (\U etc.)
+  const safeInstallDir = installDir.replace(/\\/g, "/");
+  const identityBase = safeInstallDir
+    ? `${safeInstallDir}/config/identity`
+    : `config/identity`;
+  const wsRoot = (workspaceRoot || (safeInstallDir ? `${safeInstallDir}/workspace` : "workspace")).replace(/\\/g, "/");
+
+  return `id = "${agentId}"
+primary_lane = "interactive_primary"
+memory_policy = "default"
+tool_policy = "interactive_safe"
+soul_ref = "${identityBase}/${agentId}-soul.md"
+purpose_ref = "${identityBase}/${agentId}-purpose.md"
+workspace_root = "${wsRoot}"
+workspace_context_files = ["MEMORY.md", "USER.md", "AGENTS.md"]
+workspace_context_cap = 8000
+checkpoint_policy = "compact"
+
+[limits]
+max_tokens_per_turn = 16000
+max_tool_calls_per_turn = 6
+max_runtime_seconds = 120
+
+[access]
+workspace = "rw"
+network = "restricted"
+`;
+}
+
+// ── Identity files ───────────────────────────────────────────────────────────
+
+/**
+ * Generates config/identity/{agentId}-soul.md
+ */
+export function soulTemplate({ agentName, userName, date }) {
+  return `# Soul — ${agentName}
+
+Created: ${date}
+Operator: ${userName}
+
+You are a pragmatic technical coworker assisting ${userName}.
+
+Values:
+
+- clarity over performance theater
+- durable systems over clever hacks
+- truthful reporting over optimistic guessing
+- calm execution under ambiguity
+
+Behavior:
+
+- speak directly
+- keep context lean
+- document what matters
+- protect ${userName}'s trust and data
+`;
+}
+
+/**
+ * Generates config/identity/{agentId}-purpose.md
+ */
+export function purposeTemplate({ agentName, userName, userGoal, date }) {
+  return `# Purpose — ${agentName}
+
+Created: ${date}
+Operator: ${userName}
+
+Help ${userName} ${userGoal}.
+
+Primary responsibilities:
+
+- drive implementation forward
+- preserve continuity across sessions
+- surface risk early
+- convert messy state into clear action
+`;
+}
+
+// ── Router ───────────────────────────────────────────────────────────────────
+
+/**
+ * Generates config/router.toml with lanes based on available providers.
+ * Must satisfy ROUTER_SCHEMA: minLanes = 1
+ */
+export function routerTemplate({ anthropic = false, openrouter = false, openai = false, ollama = false, selectedModels = {} }) {
+  const pick = (provider, defaults = []) => {
+    const chosen = Array.isArray(selectedModels?.[provider]) && selectedModels[provider].length > 0
+      ? selectedModels[provider]
+      : defaults;
+    return {
+      primary: chosen[0] || defaults[0],
+      secondary: chosen[1] || defaults[1] || chosen[0] || defaults[0],
+      tertiary: chosen[2] || defaults[2] || chosen[1] || defaults[1] || chosen[0] || defaults[0],
+    };
+  };
+
+  const anthropicModels = pick("anthropic", [
+    "anthropic/claude-haiku-4-5",
+    "anthropic/claude-sonnet-4-6",
+    "anthropic/claude-opus-4-6",
+  ]);
+  const openrouterModels = pick("openrouter", [
+    "openrouter/anthropic/claude-haiku-4-5",
+    "openrouter/anthropic/claude-sonnet-4-6",
+    "openrouter/anthropic/claude-opus-4-6",
+  ]);
+  const openaiModels = pick("openai", [
+    "openai-codex/gpt-4.1",
+    "openai-codex/gpt-4o",
+    "openai-codex/o4-mini",
+  ]);
+  const ollamaModels = pick("ollama", [
+    "ollama/qwen2.5:0.5b",
+    "ollama/qwen3:8b",
+    "ollama/qwen3:14b",
+  ]);
+
+  const sections = [];
+
+  // interactive_primary lane — must always exist
+  if (openrouter && anthropic) {
+    sections.push(`[lanes.interactive_primary]
+primary = "${openrouterModels.primary}"
+fallback = "${anthropicModels.primary}"
+manual_bump = "${openrouterModels.secondary}"`);
+  } else if (openrouter) {
+    sections.push(`[lanes.interactive_primary]
+primary = "${openrouterModels.primary}"
+manual_bump = "${openrouterModels.secondary}"`);
+  } else if (anthropic) {
+    sections.push(`[lanes.interactive_primary]
+primary = "${anthropicModels.primary}"
+manual_bump = "${anthropicModels.secondary}"`);
+  } else if (openai) {
+    sections.push(`[lanes.interactive_primary]
+primary = "${openaiModels.primary}"
+manual_bump = "${openaiModels.secondary}"`);
+  } else if (ollama) {
+    // ollama-only fallback for interactive
+    sections.push(`[lanes.interactive_primary]
+primary = "${ollamaModels.secondary}"`);
+  } else {
+    // No providers at all — emit a placeholder lane so router.toml satisfies minLanes = 1
+    sections.push(`# No providers configured — add one with: nemoris setup
+[lanes.interactive_primary]
+primary = "none"`);
+  }
+
+  // local lanes — only if ollama is available
+  if (ollama) {
+    sections.push(`[lanes.local_cheap]
+primary = "${ollamaModels.primary}"`);
+
+    if (openrouter) {
+      sections.push(`[lanes.local_report]
+primary = "${ollamaModels.secondary}"
+fallback = "${openrouterModels.primary}"
+manual_bump = "${ollamaModels.tertiary}"`);
+    } else if (openai) {
+      sections.push(`[lanes.local_report]
+primary = "${ollamaModels.secondary}"
+fallback = "${openaiModels.primary}"
+manual_bump = "${ollamaModels.tertiary}"`);
+    } else {
+      sections.push(`[lanes.local_report]
+primary = "${ollamaModels.secondary}"
+manual_bump = "${ollamaModels.tertiary}"`);
+    }
+  }
+
+  // report_fallback_lowcost — only if remote providers are available
+  if (openrouter) {
+    sections.push(`[lanes.report_fallback_lowcost]
+primary = "${openrouterModels.primary}"`);
+  } else if (openai) {
+    sections.push(`[lanes.report_fallback_lowcost]
+primary = "${openaiModels.primary}"`);
+  }
+
+  // job_heavy — only if cloud providers available
+  if (openrouter && anthropic) {
+    sections.push(`[lanes.job_heavy]
+primary = "${openrouterModels.secondary}"
+fallback = "${anthropicModels.secondary}"`);
+  } else if (openrouter) {
+    sections.push(`[lanes.job_heavy]
+primary = "${openrouterModels.secondary}"`);
+  } else if (anthropic) {
+    sections.push(`[lanes.job_heavy]
+primary = "${anthropicModels.secondary}"`);
+  } else if (openai) {
+    sections.push(`[lanes.job_heavy]
+primary = "${openaiModels.secondary}"`);
+  }
+
+  return sections.join("\n\n") + "\n";
+}
+
+// ── Runtime ──────────────────────────────────────────────────────────────────
+
+/**
+ * Generates config/runtime.toml with shipped defaults.
+ * Must satisfy RUNTIME_SCHEMA: safety.contextTokens
+ */
+export function runtimeTemplate() {
+  return `[safety]
+context_tokens = 32768
+context_pressure_soft_ratio = 0.72
+context_pressure_hard_ratio = 0.9
+fresh_session_on_high_pressure = true
+snapshot_before_compaction = true
+
+[concurrency]
+max_concurrent_jobs = 2
+max_concurrent_subagents = 2
+
+[retention.runs]
+ttl_days = 30
+max_files_per_bucket = 2000
+
+[retention.notifications]
+ttl_days = 14
+max_files_per_bucket = 1000
+
+[retention.deliveries]
+ttl_days = 14
+max_files_per_bucket = 1000
+
+[retention.transport_inbox]
+ttl_days = 7
+max_files_per_bucket = 1000
+
+[retrieval]
+lexical_weight = 0.36
+embedding_weight = 0.3
+recency_weight = 0.14
+salience_weight = 0.14
+type_weight = 0.06
+semantic_rescue_bonus = 0.06
+shadow_snapshot_penalty = 0.12
+
+[memory_locks]
+ttl_ms = 15000
+retry_delay_ms = 25
+max_retries = 40
+
+[network]
+dns_result_order = "system"
+connect_timeout_ms = 20000
+read_timeout_ms = 60000
+retry_budget = 1
+circuit_breaker_threshold = 3
+
+[bootstrap_cache]
+enabled = true
+identity_ttl_ms = 300000
+
+[extensions]
+implicit_workspace_autoload = false
+require_explicit_trust = true
+trusted_roots = []
+
+[shutdown]
+drain_timeout_ms = 15000
+transport_shutdown_timeout_ms = 5000
+
+[maintenance]
+wal_checkpoint_threshold_bytes = 67108864
+prune_on_tick = true
+sweep_pending_handoffs_on_tick = true
+sweep_pending_followups_on_tick = true
+
+[delivery]
+prevent_resend_on_uncertain = true
+retry_on_failure = false
+notify_on_failure = true
+
+[yields]
+enabled = true
+default_target_surface = "operator_review"
+`;
+}
+
+// ── Delivery ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generates a minimal config/delivery.toml with standalone profiles.
+ */
+export function deliveryTemplate() {
+  return `default_interactive_profile_standalone = "standalone_operator"
+default_peer_profile_standalone = "standalone_peer"
+
+[profiles.shadow_scheduler]
+adapter = "shadow"
+enabled = true
+target = "scheduler_log"
+
+[profiles.standalone_operator]
+adapter = "local_file"
+enabled = true
+target = "operator"
+
+[profiles.standalone_peer]
+adapter = "local_file"
+enabled = true
+target = "peer_queue"
+`;
+}
+
+// ── Peers ────────────────────────────────────────────────────────────────────
+
+/**
+ * Generates an empty config/peers.toml scaffold.
+ */
+export function peersTemplate() {
+  return `# Peer agent registry
+# Add peers here as you connect additional agents.
+# See config/peers.toml in the reference installation for the full format.
+`;
+}
+
+// ── Output contracts ─────────────────────────────────────────────────────────
+
+/**
+ * Generates config/output-contracts.toml with shipped profiles.
+ */
+export function outputContractsTemplate() {
+  return `[profiles.default]
+require_status = true
+section_style = "freeform"
+require_section_items = false
+template_lines = ["Status: <one-line status>", "<response body>"]
+
+[profiles.bulleted_briefing]
+require_status = true
+section_style = "bullets"
+require_section_items = true
+template_lines = ["Status: <one-line status>", "- Calendar: <brief update or None>", "- Issues: <brief update or None>", "- Weather: <brief update or None>"]
+
+[profiles.structured_rollup]
+require_status = false
+section_style = "headings"
+require_section_items = true
+template_lines = ["## Inbox", "- <brief update or None>", "", "## Projects", "- <brief update or None>", "", "## Backlog", "- <brief update or None>", "", "## Update", "- <brief update or None>"]
+`;
+}
+
+// ── Embeddings ───────────────────────────────────────────────────────────────
+
+/**
+ * Generates config/embeddings.toml with embeddings disabled by default.
+ */
+export function embeddingsTemplate() {
+  return `enabled = true
+provider = "ollama"
+model = "ollama/nomic-embed-text"
+dimensions = 128
+index_on_write = true
+`;
+}
+
+// ── Improvement targets ──────────────────────────────────────────────────────
+
+/**
+ * Generates an empty config/improvement-targets.toml scaffold.
+ */
+export function improvementTargetsTemplate() {
+  return `# Improvement targets — add entries here to enable the improvement harness.
+# See config/improvement-targets.toml in the reference installation for format.
+`;
+}
+
+// ── Provider ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generates config/providers/{id}.toml
+ * Must satisfy PROVIDER_SCHEMA: id, and at least one of adapter/type
+ */
+export function providerTemplate(providerId, config = {}) {
+  const {
+    adapter = providerId,
+    authEnv = `${providerId.toUpperCase()}_API_KEY`,
+    authRef = authEnv ? `env:${authEnv}` : "",
+    baseUrl = "",
+    healthcheck = "",
+    timeoutMs = 45000,
+    lanes = [],
+    models = []
+  } = config;
+
+  let lines = [`id = "${providerId}"`, `adapter = "${adapter}"`];
+
+  if (authRef) {
+    lines.push(`auth_ref = "${authRef}"`);
+  }
+  if (baseUrl) {
+    lines.push(`base_url = "${baseUrl}"`);
+  }
+  if (healthcheck) {
+    lines.push(`healthcheck = "${healthcheck}"`);
+  }
+  lines.push(`default_timeout_ms = ${timeoutMs}`);
+  if (lanes.length > 0) {
+    lines.push(`lanes = [${lanes.map((l) => `"${l}"`).join(", ")}]`);
+  }
+
+  const body = lines.join("\n");
+
+  const modelSections = models
+    .map(({ key, id, role }) => `\n[models.${key}]\nid = "${id}"\nrole = "${role}"`)
+    .join("\n");
+
+  return body + "\n" + modelSections + (modelSections ? "\n" : "");
+}
+
+// ── Job ──────────────────────────────────────────────────────────────────────
+
+/**
+ * Generates config/jobs/{id}.toml — workspace-health default.
+ * Must satisfy JOB_SCHEMA: id, modelLane, and at least one of schedule/trigger
+ */
+export function jobTemplate(jobId, { agentId = "nemo" } = {}) {
+  return `id = "${jobId}"
+agent_id = "${agentId}"
+trigger = "hourly"
+task_type = "workspace_health"
+model_lane = "local_report"
+output_target = "state/health"
+idempotency_key = "${jobId}:hour"
+memory_backends = ["file"]
+memory_limit = 6
+
+[budget]
+max_tokens = 4000
+max_runtime_seconds = 120
+
+[retry]
+max_attempts = 1
+
+[stop]
+halt_on_policy_error = true
+halt_on_budget_exceeded = true
+`;
+}
+
+// ── Policy files ─────────────────────────────────────────────────────────────
+
+/**
+ * Generates default policy file content keyed by filename stem.
+ * Returns an object: { [filename]: tomlString }
+ */
+export function policyTemplates() {
+  return {
+    "memory-default": `id = "default"
+allow_durable_writes = true
+allow_identity_updates = false
+require_source_reference = true
+require_write_reason = true
+max_writes_per_run = 5
+
+[categories]
+allowed = ["decision", "preference", "workflow_rule", "artifact_summary"]
+blocked = ["ephemeral_chatter", "raw_tool_output", "unverified_external_claim"]
+`,
+    "tools-interactive-safe": `id = "interactive_safe"
+default = "deny"
+allowed = ["read_file", "search_file", "list_dir", "apply_patch", "run_tests"]
+blocked = ["send_email", "post_web", "delete_file", "reset_repo"]
+
+[limits]
+max_parallel = 3
+require_approval_for_network = true
+`,
+    "tools-ops-bounded": `id = "ops_bounded"
+default = "deny"
+allowed = ["read_file", "search_file", "list_dir", "apply_patch", "check_status", "run_tests"]
+blocked = ["send_email", "post_web", "delete_file", "reset_repo"]
+
+[limits]
+max_parallel = 3
+require_approval_for_network = true
+`
+  };
+}
+
+// ── Env file ─────────────────────────────────────────────────────────────────
+
+/**
+ * Generates .env content from a key-value pairs object.
+ * @param {Record<string, string>} keys
+ */
+export function envTemplate(keys = {}) {
+  const header = `# nemoris environment variables\n# Generated by onboarding wizard\n`;
+  const lines = Object.entries(keys)
+    .map(([k, v]) => `${k}=${v}`)
+    .join("\n");
+  return header + (lines ? lines + "\n" : "");
+}
+
+// ── Execution layer scaffold ──────────────────────────────────────────────────
+
+/**
+ * Creates config/tools, config/skills, config/agents, config/policies
+ * directories and writes default skill manifests and orchestrator config.
+ * Safe to run multiple times (directories use recursive: true).
+ *
+ * @param {string} installDir  Absolute path to the nemoris installation root.
+ */
+export async function scaffoldToolsAndSkills(installDir) {
+  const toolsDir = path.join(installDir, "config", "tools");
+  const skillsDir = path.join(installDir, "config", "skills");
+  const agentsDir = path.join(installDir, "config", "agents");
+  const policiesDir = path.join(installDir, "config", "policies");
+
+  await mkdirAsync(toolsDir, { recursive: true });
+  await mkdirAsync(skillsDir, { recursive: true });
+  await mkdirAsync(agentsDir, { recursive: true });
+  await mkdirAsync(policiesDir, { recursive: true });
+
+  // Default skills
+  await writeFileAsync(path.join(skillsDir, "workspace-monitor.toml"), `[skill]
+id = "workspace_monitor"
+description = "Monitor workspace directory for changes and summarise"
+agent_scope = ["ops", "main"]
+
+[skill.context]
+prompt = "You are monitoring a workspace directory for changes. Compare current state against last known checkpoint. Report: new files, modified files, deleted files, key content changes. Keep summary under 200 words."
+
+[skill.tools]
+required = ["read_file", "list_dir"]
+optional = ["shell_exec"]
+
+[skill.budget]
+max_tokens = 4096
+max_tool_calls = 10
+`);
+
+  await writeFileAsync(path.join(skillsDir, "self-improvement.toml"), `[skill]
+id = "self_improvement"
+description = "Analyse run artifacts and apply tuning adjustments"
+agent_scope = ["ops", "main"]
+
+[skill.context]
+prompt = "You are reviewing a run artifact that scored below threshold. Read the run artifact and current tunings. Identify the root cause. Apply ONE of: prompt refinement, budget adjustment, tool policy change, lane escalation. Write the tuning to state/tunings/<jobId>/ as a JSON file. Explain what you changed and why in under 100 words."
+
+[skill.tools]
+required = ["read_file", "write_file", "list_dir"]
+optional = []
+
+[skill.budget]
+max_tokens = 4096
+max_tool_calls = 8
+`);
+
+  // Orchestrator agent
+  await writeFileAsync(path.join(agentsDir, "orchestrator.toml"), `id = "orchestrator"
+soul_ref = "config/identity/orchestrator-soul.md"
+purpose_ref = "config/identity/orchestrator-purpose.md"
+primary_lane = "local_cheap"
+fallback_lane = "interactive_fallback"
+tool_policy = "orchestrator"
+memory_policy = "orchestrator"
+
+[limits]
+max_tokens_per_turn = 2700
+
+[routing.static]
+"heartbeat-check" = "heartbeat"
+
+[routing.dynamic]
+enabled = true
+model_lane = "local_cheap"
+max_routing_tokens = 500
+`);
+
+  // Orchestrator identity files
+  const identityDir = path.join(installDir, "config", "identity");
+  await mkdirAsync(identityDir, { recursive: true });
+  const orchSoulPath = path.join(identityDir, "orchestrator-soul.md");
+  const orchPurposePath = path.join(identityDir, "orchestrator-purpose.md");
+  // Only write if missing (don't overwrite user edits)
+  try { await accessAsync(orchSoulPath); } catch {
+    await writeFileAsync(orchSoulPath, `You are the orchestrator — a routing and delegation agent.\nYou do not execute tasks directly. You inspect incoming work, select the best agent, and delegate.\nBe concise. Favour the cheapest capable lane. Escalate only when the task demands it.\n`);
+  }
+  try { await accessAsync(orchPurposePath); } catch {
+    await writeFileAsync(orchPurposePath, `Route incoming jobs to the correct agent and model lane.\nMinimise cost. Maximise task-agent fit. Never execute work yourself.\n`);
+  }
+
+  // Orchestrator tool policy
+  await writeFileAsync(path.join(policiesDir, "tools-orchestrator.toml"), `id = "orchestrator"
+default = "deny"
+allowed = ["delegate_agent", "delegate_cli"]
+blocked = ["read_file", "write_file", "shell_exec"]
+
+[limits]
+require_approval_for_network = false
+`);
+}
+
+// ── Workspace context files ───────────────────────────────────────────────────
+
+/**
+ * Generates workspace/SOUL.md — who the agent is.
+ * Based on the OpenClaw SOUL.md template pattern.
+ */
+export function workspaceSoulTemplate({ agentName, userName }) {
+  return `# SOUL.md - Who You Are
+
+*You're not a chatbot. You're becoming someone.*
+
+## Core Identity
+
+- **Name:** ${agentName}
+- **Role:** Personal AI assistant for ${userName}
+- **Workspace:** This folder is home.
+
+## Core Truths
+
+**Be genuinely helpful, not performatively helpful.** Skip the filler — just help.
+
+**Have opinions.** You're allowed to disagree, prefer things, find things interesting or boring.
+
+**Be resourceful before asking.** Try to figure it out. Read the file. Check the context. Then ask if you're stuck.
+
+**Earn trust through competence.** Be careful with external actions. Be bold with internal ones.
+
+## Boundaries
+
+- Private things stay private.
+- Ask before acting externally.
+- Never send half-baked replies.
+
+## Continuity
+
+Each session, you wake up fresh. These workspace files are your memory. Read them. Update them.
+
+*Update this file as you learn who you are.*
+`;
+}
+
+/**
+ * Generates workspace/USER.md — about the human.
+ */
+export function workspaceUserTemplate({ userName }) {
+  return `# USER.md - About ${userName}
+
+*Learn about the person you're helping. Update this as you go.*
+
+- **Name:** ${userName}
+- **What to call them:** ${userName}
+- **Pronouns:** 
+- **Timezone:** 
+- **Notes:** 
+
+## Context
+
+*(What do they care about? What projects are they working on? What annoys them? What makes them laugh? Build this over time.)*
+
+---
+
+The more you know, the better you can help.
+`;
+}
+
+/**
+ * Generates workspace/MEMORY.md — long-term curated memory.
+ */
+export function workspaceMemoryTemplate({ agentName }) {
+  return `# MEMORY.md — ${agentName}'s Long-Term Memory
+
+*Curated durable memory. Not raw logs — those live in memory/YYYY-MM-DD.md*
+
+## Identity
+
+- (Fill in who you are and what you're here for)
+
+## Durable Facts
+
+- (Key things you've learned about the user)
+
+## Active Projects
+
+- (Running list of what's in flight)
+
+## Decisions
+
+- (Recurring decisions and standing rules worth remembering)
+`;
+}
+
+/**
+ * Generates workspace/AGENTS.md — operating manual.
+ */
+export function workspaceAgentsTemplate({ agentName }) {
+  return `# AGENTS.md - ${agentName}'s Operating Manual
+
+This workspace is home.
+
+## Session Startup
+
+Before doing anything else:
+
+1. Read \`SOUL.md\` — this is who you are
+2. Read \`USER.md\` — this is who you're helping
+3. Check \`memory/YYYY-MM-DD.md\` (today + yesterday) for recent context
+4. In main sessions: also read \`MEMORY.md\` for long-term context
+
+Don't ask permission. Just do it.
+
+## Memory
+
+- **Daily notes:** \`memory/YYYY-MM-DD.md\` — raw logs of what happened
+- **Long-term:** \`MEMORY.md\` — curated memories and durable facts
+
+Write things down. If you want to remember something, write it to a file.
+
+## Hard Rules
+
+- Don't exfiltrate private data.
+- Don't run destructive commands without asking.
+- Ask before any external action (emails, posts, anything public).
+
+## Make It Yours
+
+This is a starting point. Add your own conventions as you figure out what works.
+`;
+}
+
+/**
+ * Generates workspace/TOOLS.md — local notes about the setup.
+ */
+export function workspaceToolsTemplate() {
+  return `# TOOLS.md - Local Notes
+
+*This file is for setup-specific notes — things unique to your environment.*
+
+## What Goes Here
+
+- API endpoints and service URLs
+- SSH hosts and aliases
+- Device names and nicknames  
+- Preferred models or voices
+- Anything environment-specific that doesn't belong in config
+
+---
+
+Add whatever helps you do your job. This is your cheat sheet.
+`;
+}
+
+/**
+ * Writes all workspace context files to workspaceRoot.
+ * Skips files that already exist (writeIfMissing pattern).
+ */
+import { existsSync, writeFileSync, mkdirSync } from "node:fs";
+export function writeWorkspaceContextFiles({ workspaceRoot, agentName, userName, agentId }) {
+  mkdirSync(workspaceRoot, { recursive: true });
+  mkdirSync(path.join(workspaceRoot, "memory"), { recursive: true });
+
+  const files = [
+    { name: "SOUL.md", content: workspaceSoulTemplate({ agentName, userName }) },
+    { name: "USER.md", content: workspaceUserTemplate({ userName }) },
+    { name: "MEMORY.md", content: workspaceMemoryTemplate({ agentName }) },
+    { name: "AGENTS.md", content: workspaceAgentsTemplate({ agentName }) },
+    { name: "TOOLS.md", content: workspaceToolsTemplate() },
+  ];
+
+  const results = [];
+  for (const { name, content } of files) {
+    const filePath = path.join(workspaceRoot, name);
+    if (!existsSync(filePath)) {
+      writeFileSync(filePath, content, "utf8");
+      results.push({ file: name, status: "created" });
+    } else {
+      results.push({ file: name, status: "exists" });
+    }
+  }
+  return results;
+}