bazilion 0.0.0

package/apps/daemon/src/runtime/providers/registry.ts

@@ -0,0 +1,374 @@
+import type { BazilionDb } from '../../core/index.ts'
+import {
+  hasCredentials as hasOpenAICodexCredentials,
+  loadAccessToken as loadOpenAICodexAccessToken,
+} from '../auth/openai-codex.ts'
+import { piProvider } from './pi-adapter.ts'
+import { type RetryOptions, withRetry } from './retry.ts'
+import type { Provider } from './types.ts'
+
+export interface ProviderConfig {
+  anthropic?: { apiKey: string; baseURL?: string }
+  openai?: { apiKey: string; baseURL?: string }
+  /** ChatGPT/Codex OAuth. The apiKey is fetched+refreshed lazily from secrets. */
+  openaiCodex?: { db: BazilionDb; authToken: string }
+  google?: { apiKey: string; baseURL?: string }
+  azureOpenai?: { apiKey: string; baseURL?: string }
+  bedrock?: { apiKey?: string } // auth via AWS SDK env (AWS_PROFILE / AWS_ACCESS_KEY_ID / ...)
+  googleVertex?: Record<string, never> // auth via ADC + GOOGLE_CLOUD_PROJECT
+  mistral?: { apiKey: string; baseURL?: string }
+  groq?: { apiKey: string; baseURL?: string }
+  cerebras?: { apiKey: string; baseURL?: string }
+  xai?: { apiKey: string; baseURL?: string }
+  zai?: { apiKey: string; baseURL?: string }
+  huggingface?: { apiKey: string; baseURL?: string }
+  openrouter?: { apiKey: string; baseURL?: string }
+  vercelAiGateway?: { apiKey: string; baseURL?: string }
+  lmstudio?: { baseURL?: string; apiKey?: string }
+  ollama?: { baseURL?: string; apiKey?: string }
+}
+
+export interface ResolvedModel {
+  provider: Provider
+  model: string
+}
+
+/**
+ * Env var → provider config. Empty / missing vars leave that provider unconfigured.
+ *
+ * Pass `oauth` (the daemon's `{db, authToken}` pair) to also pick up
+ * OAuth-backed providers whose credentials live in the `secrets` table
+ * (currently: `openai-codex` / ChatGPT). Env-only callers can omit it —
+ * those providers just won't be configured.
+ */
+export function loadProviderConfigFromEnv(
+  env: NodeJS.ProcessEnv = process.env,
+  oauth?: { db: BazilionDb; authToken: string },
+): ProviderConfig {
+  const config: ProviderConfig = {
+    lmstudio: {
+      ...(env.LMSTUDIO_URL !== undefined ? { baseURL: env.LMSTUDIO_URL } : {}),
+      ...(env.LMSTUDIO_API_KEY !== undefined ? { apiKey: env.LMSTUDIO_API_KEY } : {}),
+    },
+    ollama: {
+      ...(env.OLLAMA_URL !== undefined ? { baseURL: env.OLLAMA_URL } : {}),
+      ...(env.OLLAMA_API_KEY !== undefined ? { apiKey: env.OLLAMA_API_KEY } : {}),
+    },
+  }
+  if (env.ANTHROPIC_API_KEY || env.ANTHROPIC_OAUTH_TOKEN) {
+    config.anthropic = { apiKey: env.ANTHROPIC_OAUTH_TOKEN ?? env.ANTHROPIC_API_KEY ?? '' }
+  }
+  if (env.OPENAI_API_KEY) config.openai = { apiKey: env.OPENAI_API_KEY }
+  if (env.GEMINI_API_KEY) config.google = { apiKey: env.GEMINI_API_KEY }
+  if (env.AZURE_OPENAI_API_KEY) config.azureOpenai = { apiKey: env.AZURE_OPENAI_API_KEY }
+  if (
+    env.AWS_PROFILE ||
+    env.AWS_BEARER_TOKEN_BEDROCK ||
+    (env.AWS_ACCESS_KEY_ID && env.AWS_SECRET_ACCESS_KEY)
+  ) {
+    config.bedrock = {}
+  }
+  if (env.GOOGLE_CLOUD_PROJECT && env.GOOGLE_CLOUD_LOCATION) {
+    config.googleVertex = {}
+  }
+  if (env.MISTRAL_API_KEY) config.mistral = { apiKey: env.MISTRAL_API_KEY }
+  if (env.GROQ_API_KEY) config.groq = { apiKey: env.GROQ_API_KEY }
+  if (env.CEREBRAS_API_KEY) config.cerebras = { apiKey: env.CEREBRAS_API_KEY }
+  if (env.XAI_API_KEY) config.xai = { apiKey: env.XAI_API_KEY }
+  if (env.ZAI_API_KEY) config.zai = { apiKey: env.ZAI_API_KEY }
+  if (env.HF_TOKEN) config.huggingface = { apiKey: env.HF_TOKEN }
+  if (env.OPENROUTER_API_KEY) config.openrouter = { apiKey: env.OPENROUTER_API_KEY }
+  if (env.AI_GATEWAY_API_KEY) config.vercelAiGateway = { apiKey: env.AI_GATEWAY_API_KEY }
+  if (oauth && hasOpenAICodexCredentials(oauth.db, oauth.authToken)) {
+    config.openaiCodex = oauth
+  }
+  return config
+}
+
+export interface ProviderRegistry {
+  resolve(modelString: string): ResolvedModel
+  list(): string[]
+}
+
+export interface ProviderRegistryOptions {
+  /** If provided, resolve() refuses any provider not in the set with "disabled by admin". */
+  enabledSet?: ReadonlySet<string>
+  /** Retry policy applied uniformly to every provider; omit for built-in defaults. */
+  retry?: RetryOptions
+}
+
+interface ProviderEntry {
+  configured: (c: ProviderConfig) => boolean
+  build: (c: ProviderConfig) => Provider
+  /** Helpful error hint when the caller references this provider but env isn't set. */
+  hint: string
+}
+
+const PROVIDERS: Record<string, ProviderEntry> = {
+  anthropic: {
+    configured: (c) => !!c.anthropic,
+    build: (c) =>
+      piProvider({
+        providerName: 'anthropic',
+        fallbackApi: 'anthropic-messages',
+        apiKey: c.anthropic?.apiKey,
+        baseUrl: c.anthropic?.baseURL,
+      }),
+    hint: 'ANTHROPIC_API_KEY or ANTHROPIC_OAUTH_TOKEN',
+  },
+  openai: {
+    configured: (c) => !!c.openai,
+    build: (c) =>
+      piProvider({
+        providerName: 'openai',
+        fallbackApi: 'openai-completions',
+        apiKey: c.openai?.apiKey,
+        baseUrl: c.openai?.baseURL,
+      }),
+    hint: 'OPENAI_API_KEY',
+  },
+  'openai-codex': {
+    configured: (c) => !!c.openaiCodex,
+    // Pi-ai's `openai-codex-responses` speaks the ChatGPT backend's Responses
+    // API (https://chatgpt.com/backend-api) using a JWT access token as the
+    // apiKey. We pass a supplier that refreshes lazily via the OAuth refresh
+    // token, so the registry-cached Provider instance stays valid across
+    // expiries without rebuild.
+    build: (c) => {
+      const openaiCodex = c.openaiCodex
+      if (!openaiCodex) throw new Error('openai-codex not configured')
+      return piProvider({
+        providerName: 'openai-codex',
+        fallbackApi: 'openai-codex-responses',
+        apiKey: () => loadOpenAICodexAccessToken(openaiCodex.db, openaiCodex.authToken),
+      })
+    },
+    hint: 'run `bazilion auth openai login` (or click Connect on /config)',
+  },
+  google: {
+    configured: (c) => !!c.google,
+    build: (c) =>
+      piProvider({
+        providerName: 'google',
+        fallbackApi: 'google-generative-ai',
+        apiKey: c.google?.apiKey,
+        baseUrl: c.google?.baseURL,
+      }),
+    hint: 'GEMINI_API_KEY',
+  },
+  'google-vertex': {
+    configured: (c) => !!c.googleVertex,
+    build: () => piProvider({ providerName: 'google-vertex', fallbackApi: 'google-vertex' }),
+    hint: 'GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION + ADC (gcloud auth)',
+  },
+  'azure-openai': {
+    configured: (c) => !!c.azureOpenai,
+    build: (c) =>
+      piProvider({
+        providerName: 'azure-openai',
+        fallbackApi: 'azure-openai-responses',
+        apiKey: c.azureOpenai?.apiKey,
+        baseUrl: c.azureOpenai?.baseURL,
+      }),
+    hint: 'AZURE_OPENAI_API_KEY',
+  },
+  bedrock: {
+    configured: (c) => !!c.bedrock,
+    build: () =>
+      piProvider({
+        providerName: 'bedrock',
+        piProviderName: 'amazon-bedrock',
+        fallbackApi: 'bedrock-converse-stream',
+      }),
+    hint: 'AWS_PROFILE or AWS_ACCESS_KEY_ID+AWS_SECRET_ACCESS_KEY',
+  },
+  mistral: {
+    configured: (c) => !!c.mistral,
+    build: (c) =>
+      piProvider({
+        providerName: 'mistral',
+        fallbackApi: 'openai-completions',
+        apiKey: c.mistral?.apiKey,
+        baseUrl: c.mistral?.baseURL,
+      }),
+    hint: 'MISTRAL_API_KEY',
+  },
+  groq: {
+    configured: (c) => !!c.groq,
+    build: (c) =>
+      piProvider({
+        providerName: 'groq',
+        fallbackApi: 'openai-completions',
+        apiKey: c.groq?.apiKey,
+        baseUrl: c.groq?.baseURL,
+      }),
+    hint: 'GROQ_API_KEY',
+  },
+  cerebras: {
+    configured: (c) => !!c.cerebras,
+    build: (c) =>
+      piProvider({
+        providerName: 'cerebras',
+        fallbackApi: 'openai-completions',
+        apiKey: c.cerebras?.apiKey,
+        baseUrl: c.cerebras?.baseURL,
+      }),
+    hint: 'CEREBRAS_API_KEY',
+  },
+  xai: {
+    configured: (c) => !!c.xai,
+    build: (c) =>
+      piProvider({
+        providerName: 'xai',
+        fallbackApi: 'openai-completions',
+        apiKey: c.xai?.apiKey,
+        baseUrl: c.xai?.baseURL,
+      }),
+    hint: 'XAI_API_KEY',
+  },
+  zai: {
+    configured: (c) => !!c.zai,
+    build: (c) =>
+      piProvider({
+        providerName: 'zai',
+        fallbackApi: 'openai-completions',
+        apiKey: c.zai?.apiKey,
+        baseUrl: c.zai?.baseURL,
+      }),
+    hint: 'ZAI_API_KEY',
+  },
+  huggingface: {
+    configured: (c) => !!c.huggingface,
+    build: (c) =>
+      piProvider({
+        providerName: 'huggingface',
+        fallbackApi: 'openai-completions',
+        apiKey: c.huggingface?.apiKey,
+        baseUrl: c.huggingface?.baseURL,
+      }),
+    hint: 'HF_TOKEN',
+  },
+  openrouter: {
+    configured: (c) => !!c.openrouter,
+    build: (c) =>
+      piProvider({
+        providerName: 'openrouter',
+        fallbackApi: 'openai-completions',
+        apiKey: c.openrouter?.apiKey,
+        baseUrl: c.openrouter?.baseURL,
+      }),
+    hint: 'OPENROUTER_API_KEY',
+  },
+  'vercel-ai-gateway': {
+    configured: (c) => !!c.vercelAiGateway,
+    build: (c) =>
+      piProvider({
+        providerName: 'vercel-ai-gateway',
+        fallbackApi: 'openai-completions',
+        apiKey: c.vercelAiGateway?.apiKey,
+        baseUrl: c.vercelAiGateway?.baseURL,
+      }),
+    hint: 'AI_GATEWAY_API_KEY',
+  },
+  lmstudio: {
+    configured: () => true,
+    build: (c) =>
+      piProvider({
+        providerName: 'lmstudio',
+        fallbackApi: 'openai-completions',
+        apiKey: c.lmstudio?.apiKey ?? 'lm-studio',
+        baseUrl: c.lmstudio?.baseURL ?? 'http://127.0.0.1:1234/v1',
+      }),
+    hint: 'LMSTUDIO_URL (default http://127.0.0.1:1234/v1)',
+  },
+  ollama: {
+    configured: () => true,
+    build: (c) =>
+      piProvider({
+        providerName: 'ollama',
+        fallbackApi: 'openai-completions',
+        apiKey: c.ollama?.apiKey ?? 'ollama',
+        baseUrl: c.ollama?.baseURL ?? 'http://127.0.0.1:11434/v1',
+      }),
+    hint: 'OLLAMA_URL (default http://127.0.0.1:11434/v1)',
+  },
+}
+
+/**
+ * Model strings are `provider:model`, e.g.:
+ *   - `anthropic:claude-opus-4-6`
+ *   - `openai:gpt-4o`
+ *   - `google:gemini-2.0-flash-exp`
+ *   - `groq:llama-3.3-70b-versatile`
+ *   - `lmstudio:my-loaded-model`
+ *   - `ollama:llama2`
+ */
+export function createProviderRegistry(
+  config: ProviderConfig,
+  opts: ProviderRegistryOptions = {},
+): ProviderRegistry {
+  const cache = new Map<string, Provider>()
+  const enabledSet = opts.enabledSet
+
+  function get(name: string): Provider {
+    const cached = cache.get(name)
+    if (cached) return cached
+    const entry = PROVIDERS[name]
+    if (!entry) throw new Error(`unknown provider: ${name}`)
+    if (enabledSet && !enabledSet.has(name)) {
+      throw new Error(`${name} provider is disabled — enable it on the /config page`)
+    }
+    if (!entry.configured(config)) {
+      throw new Error(`${name} provider not configured (set ${entry.hint})`)
+    }
+    const raw = entry.build(config)
+    const provider = withRetry(raw, {
+      ...(opts.retry ?? {}),
+      onRetry: (info) => {
+        opts.retry?.onRetry?.(info)
+        console.warn(
+          `[provider/${name}] transient error on attempt ${info.attempt}, retrying in ${info.delayMs}ms: ${info.error.message.slice(0, 160)}`,
+        )
+      },
+    })
+    cache.set(name, provider)
+    return provider
+  }
+
+  return {
+    resolve(modelString: string): ResolvedModel {
+      const idx = modelString.indexOf(':')
+      if (idx === -1) {
+        throw new Error(`invalid model string "${modelString}": expected "provider:model"`)
+      }
+      const providerName = modelString.slice(0, idx)
+      const model = modelString.slice(idx + 1)
+      return { provider: get(providerName), model }
+    },
+    list() {
+      return Object.entries(PROVIDERS)
+        .filter(([name, entry]) => {
+          if (!entry.configured(config)) return false
+          if (enabledSet && !enabledSet.has(name)) return false
+          return true
+        })
+        .map(([name]) => name)
+    },
+  }
+}
+
+export interface ProviderMeta {
+  name: string
+  enabled: boolean
+  /** Hint shown when the provider isn't configured — the env var(s) required. */
+  envHint: string
+}
+
+/** List every provider the registry knows about, plus whether each is configured. */
+export function listAllProviders(config: ProviderConfig): ProviderMeta[] {
+  return Object.entries(PROVIDERS).map(([name, entry]) => ({
+    name,
+    enabled: entry.configured(config),
+    envHint: entry.hint,
+  }))
+}

package/apps/daemon/src/runtime/providers/retry.ts

@@ -0,0 +1,176 @@
+// Transient-error retry wrapper for Provider.chat().
+//
+// Applied uniformly in `createProviderRegistry` so every provider (anthropic,
+// openai, openai-codex, lmstudio, ollama, …) gets the same retry policy. A
+// one-shot upstream 5xx or rate-limit shouldn't kill the agent's turn — the
+// runtime marks the run `failed` and the user is stuck re-sending the same
+// message by hand, which is hostile UX.
+//
+// What counts as retryable is a small allowlist (server 5xx, rate-limit, a
+// handful of network errnos). Auth errors, invalid-request errors, context
+// overflows, and user-triggered aborts bypass retry entirely — they won't
+// resolve by trying again and the fast failure is the right signal.
+//
+// One hard rule: if the underlying chat already streamed text back via
+// onDelta, we can't retry — a second attempt would emit duplicated text into
+// the UI. The wrapper detects this by shadowing onDelta and tracking whether
+// the callback fired.
+
+import type { Provider, ProviderRequest, ProviderResponse } from './types.ts'
+
+export interface RetryOptions {
+  /** How many *extra* attempts beyond the first. Default 2 → up to 3 tries total. */
+  maxRetries?: number
+  /** First backoff delay in ms. Doubles each retry up to maxDelayMs. Default 500. */
+  initialDelayMs?: number
+  /** Upper bound on a single backoff delay. Default 8000. */
+  maxDelayMs?: number
+  /** Optional callback invoked before each retry (for logging / telemetry). */
+  onRetry?: (info: { attempt: number; delayMs: number; error: Error }) => void
+}
+
+/**
+ * Lowercased substrings that mark an error as worth retrying. Checked with a
+ * simple `includes` so we don't need to parse the upstream JSON shapes.
+ */
+const RETRYABLE_MARKERS: readonly string[] = [
+  'server_error',
+  'internal_server',
+  'rate_limit',
+  'rate limit',
+  'too many requests',
+  'overloaded', // covers 'overloaded_error' (Anthropic)
+  'service_unavailable',
+  'service unavailable',
+  'gateway_timeout',
+  'gateway timeout',
+  'bad_gateway',
+  'bad gateway',
+  'econnreset',
+  'etimedout',
+  'econnrefused',
+  'enotfound',
+  'eai_again',
+  'socket hang up',
+  'fetch failed',
+  'network error',
+  'connection reset',
+  'status 429',
+  'status 500',
+  'status 502',
+  'status 503',
+  'status 504',
+  '"status":429',
+  '"status":500',
+  '"status":502',
+  '"status":503',
+  '"status":504',
+]
+
+/**
+ * Non-retryable markers win over retryable ones — if an error mentions
+ * authentication or a 4xx (other than 429), retrying won't help.
+ */
+const NON_RETRYABLE_MARKERS: readonly string[] = [
+  'invalid_api_key',
+  'invalid api key',
+  'incorrect_api_key',
+  'authentication',
+  'unauthorized',
+  'permission_denied',
+  'permission denied',
+  'forbidden',
+  'invalid_request',
+  'invalid request',
+  'not_found',
+  'model_not_found',
+  'context_length_exceeded',
+  'context length',
+  'content_filter',
+  'quota_exceeded',
+  'insufficient_quota',
+  'billing',
+  'status 400',
+  'status 401',
+  'status 403',
+  'status 404',
+  'status 422',
+]
+
+export function isRetryableError(err: unknown): boolean {
+  const raw = err instanceof Error ? err.message : typeof err === 'string' ? err : String(err)
+  const msg = raw.toLowerCase()
+  for (const deny of NON_RETRYABLE_MARKERS) {
+    if (msg.includes(deny)) return false
+  }
+  for (const allow of RETRYABLE_MARKERS) {
+    if (msg.includes(allow)) return true
+  }
+  return false
+}
+
+function sleepWithAbort(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error('aborted'))
+      return
+    }
+    const t = setTimeout(() => {
+      if (signal) signal.removeEventListener('abort', onAbort)
+      resolve()
+    }, ms)
+    const onAbort = () => {
+      clearTimeout(t)
+      reject(new Error('aborted'))
+    }
+    signal?.addEventListener('abort', onAbort, { once: true })
+  })
+}
+
+export function withRetry(provider: Provider, opts: RetryOptions = {}): Provider {
+  const maxRetries = opts.maxRetries ?? 2
+  const initialDelayMs = opts.initialDelayMs ?? 500
+  const maxDelayMs = opts.maxDelayMs ?? 8_000
+
+  return {
+    name: provider.name,
+    async chat(req: ProviderRequest): Promise<ProviderResponse> {
+      let attempt = 0
+      // Use `let` so each retry gets a fresh shadow; we need to know whether
+      // onDelta fired on the *most recent* attempt.
+      let lastError: Error | null = null
+      while (true) {
+        let streamed = false
+        const wrappedReq: ProviderRequest = req.onDelta
+          ? {
+              ...req,
+              onDelta: (delta: string) => {
+                streamed = true
+                req.onDelta?.(delta)
+              },
+            }
+          : req
+        try {
+          return await provider.chat(wrappedReq)
+        } catch (err) {
+          lastError = err instanceof Error ? err : new Error(String(err))
+          if (req.signal?.aborted) throw lastError
+          if (streamed) throw lastError
+          if (attempt >= maxRetries) throw lastError
+          if (!isRetryableError(lastError)) throw lastError
+          const delayMs = Math.min(initialDelayMs * 2 ** attempt, maxDelayMs)
+          opts.onRetry?.({ attempt: attempt + 1, delayMs, error: lastError })
+          try {
+            await sleepWithAbort(delayMs, req.signal)
+          } catch {
+            // Aborted during backoff — surface the original provider error
+            // rather than the synthetic abort so the run's failure reason
+            // still points at what actually went wrong.
+            throw lastError
+          }
+          attempt++
+        }
+      }
+    },
+  }
+}

package/apps/daemon/src/runtime/providers/types.ts

@@ -0,0 +1,33 @@
+import type { ProviderMessage, ReasoningLevel, ToolCall, ToolDef } from '@bazilion/api-types'
+
+export interface ProviderRequest {
+  model: string
+  system?: string
+  messages: ProviderMessage[]
+  tools?: ToolDef[]
+  temperature?: number
+  maxTokens?: number
+  /** Reasoning/thinking level — only honored by providers/models that support it. */
+  reasoning?: ReasoningLevel
+  /** Cancels the in-flight provider call. Providers forward it to fetch(). */
+  signal?: AbortSignal
+  /** Optional token-delta callback. Fires once per streamed text chunk as the response assembles. */
+  onDelta?: (delta: string) => void
+}
+
+export type StopReason = 'stop' | 'tool_use' | 'length' | 'error'
+
+export interface ProviderResponse {
+  content: string
+  toolCalls: ToolCall[]
+  stopReason: StopReason
+  usage?: {
+    promptTokens: number
+    completionTokens: number
+  }
+}
+
+export interface Provider {
+  name: string
+  chat(request: ProviderRequest): Promise<ProviderResponse>
+}

package/apps/daemon/src/runtime/session/prompt.ts

@@ -0,0 +1,83 @@
+// Bazilion system-prompt builder. Feeds pi's `getAppendSystemPrompt()` hook
+// so the agent sees its persona + skills + workspaces + memory guidance
+// stacked on top of pi's built-in base prompt (which lists coding tools and
+// general guidelines). Pure filesystem read — no LLM, no DB.
+
+import { existsSync, readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ResolvedAgent } from '@bazilion/api-types'
+
+// Prompt order: peers first (who else is around), then persona, then tooling
+// hints, then self-knowledge, then the wake-up playbook, then the one-shot
+// bootstrap intro.
+const CONTEXT_FILE_ORDER = [
+  'AGENTS.md',
+  'SOUL.md',
+  'TOOLS.md',
+  'IDENTITY.md',
+  'HEARTBEAT.md',
+  'BOOTSTRAP.md',
+] as const
+
+export function buildSystemPrompt(agent: ResolvedAgent): string {
+  const parts: string[] = []
+
+  const contextBlocks: string[] = []
+  let bootstrapPresent = false
+  for (const file of CONTEXT_FILE_ORDER) {
+    const path = join(agent.agent.dir, file)
+    if (!existsSync(path)) continue
+    const content = readFileSync(path, 'utf8').trimEnd()
+    if (!content) continue
+    contextBlocks.push(`## ${file}\n\n${content}`)
+    if (file === 'BOOTSTRAP.md') bootstrapPresent = true
+  }
+  if (contextBlocks.length > 0) {
+    parts.push(`# Project Context\n\n${contextBlocks.join('\n\n')}`)
+  }
+  if (bootstrapPresent) {
+    parts.push(
+      'NOTE: This is your first session. After you have completed the bootstrap conversation, call the `bootstrap_done` tool to delete BOOTSTRAP.md.',
+    )
+  }
+
+  parts.push(
+    [
+      '# Agent Home',
+      '',
+      'Your private home holds who you are — identity, soul, behaviour rules, wake-up routine. It is not shared with other agents and cannot be overwritten by them. The files above (IDENTITY.md, SOUL.md, AGENTS.md, TOOLS.md, HEARTBEAT.md, BOOTSTRAP.md) live in this home.',
+      '',
+      '- To change who you are (name, vibe, personality, how you behave): use `home_write`.',
+      '- To inspect exact wording of your own files: use `home_read` or `home_list`.',
+      '- To remember facts the user told you or things you learned: use `memory_write` — NOT `home_write`.',
+      '- To produce work output (code, docs, artefacts): use `write` / `edit` — those land in your workspace, not your home.',
+    ].join('\n'),
+  )
+
+  if (agent.skills.length > 0) {
+    parts.push(
+      `# Available Skills\n\nYou have access to the following skills: ${agent.skills.join(', ')}.`,
+    )
+  }
+
+  const groupLines = [
+    '# Group',
+    '',
+    `- ${agent.group.id} (${agent.group.name}): ${agent.group.path}`,
+    '',
+    'Your group is where work product lives — code, docs, artefacts, shared scratch. It may be shared with other agents in the same group. Your coding tools (`read`, `bash`, `edit`, `write`, `grep`, `find`, `ls`) are rooted at the group directory. Never use these tools to edit your identity/soul/behaviour files — those live in your home and are reached via `home_write` / `home_read`.',
+  ]
+  parts.push(groupLines.join('\n'))
+
+  if (agent.group.userMd.trim()) {
+    parts.push(
+      `# About the User\n\nRead-only context about the human you're working with in this group. You cannot edit this — if it's wrong, say so and they will update it.\n\n${agent.group.userMd.trim()}`,
+    )
+  }
+
+  parts.push(
+    '# Memory\n\nYou share a persistent memory backend with every other agent in this group. Use `memory_write` to remember things across sessions, and `memory_search` / `memory_read` / `memory_list` to recall them. This memory is for project knowledge — codebase notes, decisions, things the user told you about the work. For personal notes about yourself (preferences, persona quirks), use `home_write` on IDENTITY.md instead. Always check memory at the start of a session: another agent in the group may have already learned something useful.',
+  )
+
+  return parts.join('\n\n---\n\n')
+}

package/apps/daemon/src/runtime/tools/bootstrap.ts

@@ -0,0 +1,22 @@
+import { existsSync, rmSync } from 'node:fs'
+import { join } from 'node:path'
+import type { ToolHandler } from './types.ts'
+
+export function bootstrapTool(agentDir: string): ToolHandler {
+  return {
+    def: {
+      name: 'bootstrap_done',
+      description:
+        'Call this once you have finished your bootstrap conversation (introduced yourself, learned the user, updated IDENTITY.md). Removes BOOTSTRAP.md so it does not appear in future sessions.',
+      parameters: { type: 'object', properties: {} },
+    },
+    async invoke() {
+      const path = join(agentDir, 'BOOTSTRAP.md')
+      if (existsSync(path)) {
+        rmSync(path)
+        return 'BOOTSTRAP.md removed. Bootstrap is complete.'
+      }
+      return 'BOOTSTRAP.md was already removed.'
+    },
+  }
+}