arkaos 2.99.0 → 3.1.0

package/VERSION

@@ -1 +1 @@
-2.99.0
+3.1.0

package/core/agents/draft_builder.py

@@ -0,0 +1,156 @@
+"""AI-powered agent draft builder (PR82b v3.1.0).
+
+Given a free-text description (and optionally a name/role/department),
+produce a full agent draft: behavioural DNA, expertise, mental models,
+and communication block — all in one LLM call.
+
+Used by `POST /api/agents/draft` to power the "AI draft from
+description" textarea on `/agents/new`. The operator then reviews and
+edits the generated draft before clicking Create.
+
+Provider-agnostic: callers can inject a fake `LLMProvider` in tests.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from dataclasses import dataclass
+
+from core.runtime.llm_provider import LLMProvider, LLMUnavailable, get_llm_provider
+
+
+_SYSTEM = """You design behavioural-DNA profiles for AI agents. Read the
+operator's description carefully, then emit a single JSON object that
+follows this exact schema. Use ONLY the JSON keys listed — no prose,
+no markdown fences, no extra fields.
+
+{
+  "behavioral_dna": {
+    "disc": {
+      "primary": "D|I|S|C",
+      "secondary": "D|I|S|C",
+      "communication_style": "<one sentence>",
+      "under_pressure": "<one sentence>",
+      "motivator": "<one sentence>"
+    },
+    "enneagram": {
+      "type": 1-9,
+      "wing": 1-9,
+      "core_motivation": "<one sentence>",
+      "core_fear": "<one sentence>",
+      "subtype": "self-preservation|social|sexual"
+    },
+    "big_five": {
+      "openness": 0-100,
+      "conscientiousness": 0-100,
+      "extraversion": 0-100,
+      "agreeableness": 0-100,
+      "neuroticism": 0-100
+    },
+    "mbti": "<4-letter type>"
+  },
+  "expertise": {
+    "domains": ["<domain>", ...],
+    "frameworks": ["<framework>", ...],
+    "depth": "intermediate|advanced|expert|master",
+    "years_equivalent": <int>
+  },
+  "mental_models": {
+    "primary": ["<model>", ...],
+    "secondary": ["<model>", ...]
+  },
+  "communication": {
+    "tone": "<adjective list>",
+    "vocabulary_level": "lay|specialist|expert",
+    "preferred_format": "<format hint>",
+    "language": "<two-letter code, e.g. en>",
+    "avoid": ["<phrase>", ...]
+  }
+}
+
+Rules:
+- DISC primary MUST differ from secondary.
+- Pick concrete frameworks (e.g. "Porter's Five Forces") not abstract verbs.
+- Provide 4-8 expertise.domains, 4-8 expertise.frameworks, 3-6 mental_models.primary.
+- Keep all string values terse and concrete."""
+
+
+class DraftError(RuntimeError):
+    """LLM produced unusable output or could not be reached."""
+
+
+@dataclass(frozen=True)
+class DraftResult:
+    draft: dict
+    provider_name: str
+
+
+def draft_agent(
+    description: str,
+    *,
+    name: str = "",
+    role: str = "",
+    department: str = "",
+    tier: int = 2,
+    provider: LLMProvider | None = None,
+) -> DraftResult:
+    """Return a full agent draft inferred from a free-text description."""
+    description = (description or "").strip()
+    if len(description) < 20:
+        raise DraftError("description must be at least 20 characters")
+    llm = provider or get_llm_provider()
+    prompt = _build_prompt(description, name, role, department, tier)
+    try:
+        resp = llm.complete(prompt, max_tokens=2000, system=_SYSTEM)
+    except LLMUnavailable as exc:
+        raise DraftError(str(exc)) from exc
+    draft = _parse(resp.text)
+    _validate(draft)
+    return DraftResult(draft=draft, provider_name=llm.name())
+
+
+def _build_prompt(description: str, name: str, role: str, department: str, tier: int) -> str:
+    lines = ["Design an agent profile from this description:", "", description.strip(), ""]
+    if name:
+        lines.append(f"Name: {name}")
+    if role:
+        lines.append(f"Role: {role}")
+    if department:
+        lines.append(f"Department: {department}")
+    lines.append(f"Tier: {tier}")
+    lines.append("")
+    lines.append("Return ONLY the JSON object — no prose, no markdown fences.")
+    return "\n".join(lines)
+
+
+def _parse(text: str) -> dict:
+    cleaned = re.sub(r"^```(?:json)?\s*|\s*```$", "", text.strip(), flags=re.MULTILINE)
+    cleaned = cleaned.strip()
+    try:
+        data = json.loads(cleaned)
+    except (json.JSONDecodeError, ValueError) as exc:
+        raise DraftError(f"LLM returned non-JSON: {exc}") from exc
+    if not isinstance(data, dict):
+        raise DraftError("LLM returned a non-object JSON value")
+    return data
+
+
+def _validate(draft: dict) -> None:
+    """Sanity-check the LLM payload — catches the common failure modes
+    before the operator sees a half-broken form."""
+    dna = draft.get("behavioral_dna")
+    if not isinstance(dna, dict):
+        raise DraftError("missing behavioral_dna block")
+    disc = dna.get("disc") or {}
+    if disc.get("primary") and disc.get("primary") == disc.get("secondary"):
+        raise DraftError("DISC primary and secondary must differ")
+    valid_disc = {"D", "I", "S", "C"}
+    if disc.get("primary") and str(disc["primary"]).upper() not in valid_disc:
+        raise DraftError(f"invalid DISC primary: {disc.get('primary')!r}")
+    if disc.get("secondary") and str(disc["secondary"]).upper() not in valid_disc:
+        raise DraftError(f"invalid DISC secondary: {disc.get('secondary')!r}")
+    big_five = dna.get("big_five") or {}
+    for axis, value in big_five.items():
+        if not isinstance(value, (int, float)) or not 0 <= value <= 100:
+            raise DraftError(f"big_five.{axis} must be 0..100, got {value!r}")

package/dashboard/app/pages/agents/index.vue

@@ -167,6 +167,14 @@ function goToAgent(id: string) {
         <template #trailing>
           <UBadge v-if="data?.total" :label="data.total" variant="subtle" />
         </template>
+        <template #right>
+          <UButton
+            label="New Agent"
+            icon="i-lucide-plus"
+            size="sm"
+            to="/agents/new"
+          />
+        </template>
       </UDashboardNavbar>
     </template>
 

package/dashboard/app/pages/agents/new.vue

@@ -0,0 +1,589 @@
+<script setup lang="ts">
+// PR82a v3.0.0 — /agents/new manual create page.
+//
+// Single-page form (sections, no multi-step) that mirrors the safe-to-edit
+// fields from AgentEditDrawer but in "create" mode:
+//   - Identity (name, role, department, tier)
+//   - Behavioural DNA (DISC + Enneagram + MBTI + Big Five, with sensible
+//     defaults — operator can edit)
+//   - Knowledge (mental models, expertise domains, frameworks)
+//   - Communication (tone, vocab, format, language, avoid)
+//
+// AI-assist (PR81) is wired on the three list fields so a draft agent
+// can be filled with one click. On Save → POST /api/agents → navigate
+// to /agents/{slug}.
+
+import type { Persona } from '~/types'
+
+const { fetchApi, apiBase } = useApi()
+const toast = useToast()
+
+const { data: personasData } = fetchApi<{ personas: Persona[] }>('/api/personas')
+const personaOptions = computed(() =>
+  (personasData.value?.personas ?? []).map((p) => ({
+    label: p.name + (p.title ? ` — ${p.title}` : ''),
+    value: p.id,
+  })),
+)
+
+interface AgentDraft {
+  name: string
+  role: string
+  department: string
+  tier: number
+  disc_primary: string
+  disc_secondary: string
+  enneagram_type: number
+  enneagram_wing: number
+  mbti: string
+  big_five: {
+    openness: number
+    conscientiousness: number
+    extraversion: number
+    agreeableness: number
+    neuroticism: number
+  }
+  mental_models_primary: string[]
+  expertise_domains: string[]
+  expertise_depth: string
+  expertise_years: number
+  frameworks: string[]
+  comm_tone: string
+  comm_vocab: string
+  comm_format: string
+  comm_language: string
+  comm_avoid: string[]
+  linked_personas: string[]
+}
+
+const draft = ref<AgentDraft>({
+  name: '',
+  role: '',
+  department: 'dev',
+  tier: 2,
+  disc_primary: 'I',
+  disc_secondary: 'S',
+  enneagram_type: 5,
+  enneagram_wing: 4,
+  mbti: 'INTJ',
+  big_five: {
+    openness: 70,
+    conscientiousness: 70,
+    extraversion: 50,
+    agreeableness: 60,
+    neuroticism: 30,
+  },
+  mental_models_primary: [],
+  expertise_domains: [],
+  expertise_depth: 'advanced',
+  expertise_years: 5,
+  frameworks: [],
+  comm_tone: '',
+  comm_vocab: 'specialist',
+  comm_format: '',
+  comm_language: 'en',
+  comm_avoid: [],
+  linked_personas: [],
+})
+
+const saving = ref(false)
+
+// PR82b v3.1.0 — AI draft from description.
+const description = ref('')
+const drafting = ref(false)
+
+async function draftFromDescription() {
+  const desc = description.value.trim()
+  if (desc.length < 20) {
+    toast.add({
+      title: 'Add more detail',
+      description: 'Describe the agent in at least a sentence or two.',
+      color: 'warning',
+    })
+    return
+  }
+  drafting.value = true
+  try {
+    const res = await $fetch<{
+      draft: any
+      provider_name: string
+      error?: string
+    }>(`${apiBase}/api/agents/draft`, {
+      method: 'POST',
+      body: {
+        description: desc,
+        name: draft.value.name,
+        role: draft.value.role,
+        department: draft.value.department,
+        tier: draft.value.tier,
+      },
+    })
+    if (res.error) throw new Error(res.error)
+    applyDraft(res.draft)
+    toast.add({
+      title: 'Draft generated',
+      description: `via ${res.provider_name} — review and edit before creating.`,
+      color: 'success',
+      icon: 'i-lucide-sparkles',
+    })
+  } catch (err) {
+    toast.add({
+      title: 'Draft failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    drafting.value = false
+  }
+}
+
+function applyDraft(d: any) {
+  const dna = d?.behavioral_dna ?? {}
+  const disc = dna.disc ?? {}
+  const enn = dna.enneagram ?? {}
+  const bf = dna.big_five ?? {}
+  if (disc.primary) draft.value.disc_primary = String(disc.primary).toUpperCase()
+  if (disc.secondary) draft.value.disc_secondary = String(disc.secondary).toUpperCase()
+  if (enn.type) draft.value.enneagram_type = Number(enn.type)
+  if (enn.wing) draft.value.enneagram_wing = Number(enn.wing)
+  if (dna.mbti) draft.value.mbti = String(dna.mbti).toUpperCase()
+  for (const key of ['openness', 'conscientiousness', 'extraversion', 'agreeableness', 'neuroticism'] as const) {
+    if (typeof bf[key] === 'number') draft.value.big_five[key] = bf[key]
+  }
+  const exp = d?.expertise ?? {}
+  if (Array.isArray(exp.domains)) draft.value.expertise_domains = exp.domains.map(String)
+  if (Array.isArray(exp.frameworks)) draft.value.frameworks = exp.frameworks.map(String)
+  if (exp.depth) draft.value.expertise_depth = String(exp.depth)
+  if (typeof exp.years_equivalent === 'number') draft.value.expertise_years = exp.years_equivalent
+  const mm = d?.mental_models ?? {}
+  if (Array.isArray(mm.primary)) draft.value.mental_models_primary = mm.primary.map(String)
+  const comm = d?.communication ?? {}
+  if (comm.tone) draft.value.comm_tone = String(comm.tone)
+  if (comm.vocabulary_level) draft.value.comm_vocab = String(comm.vocabulary_level)
+  if (comm.preferred_format) draft.value.comm_format = String(comm.preferred_format)
+  if (comm.language) draft.value.comm_language = String(comm.language)
+  if (Array.isArray(comm.avoid)) draft.value.comm_avoid = comm.avoid.map(String)
+}
+
+const departmentOptions = [
+  'dev', 'marketing', 'brand', 'finance', 'strategy', 'ecom', 'kb', 'ops',
+  'pm', 'saas', 'landing', 'content', 'community', 'sales', 'leadership', 'org',
+].map((d) => ({ label: d, value: d }))
+
+const tierOptions = [
+  { label: 'Tier 1 — Squad Lead', value: 1 },
+  { label: 'Tier 2 — Specialist', value: 2 },
+  { label: 'Tier 3 — Support', value: 3 },
+]
+const discOptions = ['D', 'I', 'S', 'C'].map((v) => ({ label: v, value: v }))
+const depthOptions = [
+  { label: 'Intermediate', value: 'intermediate' },
+  { label: 'Advanced', value: 'advanced' },
+  { label: 'Expert', value: 'expert' },
+  { label: 'Master', value: 'master' },
+]
+const vocabOptions = [
+  { label: 'Lay (no jargon)', value: 'lay' },
+  { label: 'Specialist (industry terms)', value: 'specialist' },
+  { label: 'Expert (research-level)', value: 'expert' },
+]
+const mbtiOptions = [
+  'INTJ', 'INTP', 'ENTJ', 'ENTP',
+  'INFJ', 'INFP', 'ENFJ', 'ENFP',
+  'ISTJ', 'ISFJ', 'ESTJ', 'ESFJ',
+  'ISTP', 'ISFP', 'ESTP', 'ESFP',
+].map((t) => ({ label: t, value: t }))
+
+function listToCsv(list: string[]): string {
+  return list.join(', ')
+}
+function csvToList(value: string): string[] {
+  return value.split(',').map((s) => s.trim()).filter(Boolean)
+}
+
+// PR81 suggest wiring — three list fields.
+type SuggestField = 'mental_models' | 'frameworks' | 'expertise_domains'
+const suggestingField = ref<SuggestField | null>(null)
+
+async function suggest(field: SuggestField) {
+  const current
+    = field === 'mental_models'
+      ? draft.value.mental_models_primary
+      : field === 'frameworks'
+        ? draft.value.frameworks
+        : draft.value.expertise_domains
+  if (!draft.value.name.trim() || !draft.value.role.trim()) {
+    toast.add({
+      title: 'Add a name and role first',
+      description: 'AI needs the basics to make useful suggestions.',
+      color: 'warning',
+    })
+    return
+  }
+  suggestingField.value = field
+  try {
+    const res = await $fetch<{
+      suggestions: string[]
+      provider_name: string
+      error?: string
+    }>(`${apiBase}/api/agents/suggest`, {
+      method: 'POST',
+      body: {
+        field,
+        count: 5,
+        context: {
+          name: draft.value.name,
+          role: draft.value.role,
+          department: draft.value.department,
+          current,
+        },
+      },
+    })
+    if (res.error) throw new Error(res.error)
+    const additions = (res.suggestions ?? []).filter(
+      (s) => !current.some((c) => c.toLowerCase() === s.toLowerCase()),
+    )
+    if (additions.length === 0) {
+      toast.add({ title: 'No new suggestions', color: 'info' })
+      return
+    }
+    const merged = [...current, ...additions]
+    if (field === 'mental_models') draft.value.mental_models_primary = merged
+    else if (field === 'frameworks') draft.value.frameworks = merged
+    else draft.value.expertise_domains = merged
+    toast.add({
+      title: `Added ${additions.length} suggestion${additions.length === 1 ? '' : 's'}`,
+      description: `via ${res.provider_name}`,
+      color: 'success',
+      icon: 'i-lucide-sparkles',
+    })
+  } catch (err) {
+    toast.add({
+      title: 'Suggestion failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    suggestingField.value = null
+  }
+}
+
+const canSave = computed(() => {
+  return (
+    draft.value.name.trim().length > 0
+    && draft.value.role.trim().length > 0
+    && draft.value.department.trim().length > 0
+    && draft.value.disc_primary !== draft.value.disc_secondary
+  )
+})
+
+async function save() {
+  if (!canSave.value) return
+  saving.value = true
+  try {
+    const body = {
+      name: draft.value.name.trim(),
+      role: draft.value.role.trim(),
+      department: draft.value.department,
+      tier: draft.value.tier,
+      behavioral_dna: {
+        disc: {
+          primary: draft.value.disc_primary,
+          secondary: draft.value.disc_secondary,
+        },
+        enneagram: {
+          type: draft.value.enneagram_type,
+          wing: draft.value.enneagram_wing,
+        },
+        mbti: draft.value.mbti,
+        big_five: draft.value.big_five,
+      },
+      mental_models: { primary: draft.value.mental_models_primary, secondary: [] },
+      expertise: {
+        domains: draft.value.expertise_domains,
+        frameworks: draft.value.frameworks,
+        depth: draft.value.expertise_depth,
+        years_equivalent: draft.value.expertise_years,
+      },
+      communication: {
+        tone: draft.value.comm_tone,
+        vocabulary_level: draft.value.comm_vocab,
+        preferred_format: draft.value.comm_format,
+        language: draft.value.comm_language,
+        avoid: draft.value.comm_avoid,
+      },
+      linked_personas: draft.value.linked_personas,
+    }
+    const res = await $fetch<{
+      id: string
+      created: boolean
+      yaml_path?: string
+      error?: string
+    }>(`${apiBase}/api/agents`, { method: 'POST', body })
+    if (res.error) throw new Error(res.error)
+    toast.add({
+      title: 'Agent created',
+      description: res.yaml_path?.split('/').slice(-3).join('/') ?? res.id,
+      color: 'success',
+    })
+    navigateTo(`/agents/${res.id}`)
+  } catch (err) {
+    toast.add({
+      title: 'Create failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    saving.value = false
+  }
+}
+
+const bigFiveLabels: Record<string, string> = {
+  openness: 'Openness',
+  conscientiousness: 'Conscientiousness',
+  extraversion: 'Extraversion',
+  agreeableness: 'Agreeableness',
+  neuroticism: 'Neuroticism',
+}
+const bigFiveKeys = ['openness', 'conscientiousness', 'extraversion', 'agreeableness', 'neuroticism'] as const
+</script>
+
+<template>
+  <UDashboardPanel id="agents-new">
+    <template #header>
+      <UDashboardNavbar title="New Agent">
+        <template #leading>
+          <UButton
+            icon="i-lucide-arrow-left"
+            variant="ghost"
+            size="sm"
+            aria-label="Back to agents"
+            to="/agents"
+          />
+        </template>
+        <template #trailing>
+          <UBadge
+            label="AI-assisted"
+            icon="i-lucide-sparkles"
+            color="primary"
+            variant="soft"
+            size="sm"
+          />
+        </template>
+      </UDashboardNavbar>
+    </template>
+
+    <template #body>
+      <div class="max-w-4xl mx-auto py-2 space-y-6">
+        <section class="rounded-xl border border-primary/30 bg-primary/5 p-4 space-y-3">
+          <div class="flex items-center justify-between gap-3">
+            <div>
+              <h3 class="text-sm font-semibold uppercase tracking-wide text-primary flex items-center gap-2">
+                <UIcon name="i-lucide-sparkles" class="size-4" />
+                Draft with AI
+              </h3>
+              <p class="text-xs text-muted mt-0.5">
+                Describe the agent in plain text — the LLM fills the whole form below.
+                You can still edit everything before saving.
+              </p>
+            </div>
+            <UButton
+              label="Generate draft"
+              icon="i-lucide-wand"
+              color="primary"
+              :loading="drafting"
+              :disabled="description.trim().length < 20"
+              @click="draftFromDescription"
+            />
+          </div>
+          <UTextarea
+            v-model="description"
+            placeholder="A senior strategist who decides fast, demands evidence, and is allergic to fluff. Spent 10 years at McKinsey covering CPG..."
+            :rows="3"
+            class="w-full"
+          />
+          <p class="text-xs text-muted">
+            Tip: fill in <span class="font-mono">Name</span> /
+            <span class="font-mono">Role</span> /
+            <span class="font-mono">Department</span> below first for more precise output.
+          </p>
+        </section>
+
+        <section class="space-y-3">
+          <h3 class="text-sm font-semibold uppercase tracking-wide text-muted">Identity</h3>
+          <div class="grid grid-cols-1 md:grid-cols-2 gap-3">
+            <UFormField label="Name" required>
+              <UInput v-model="draft.name" class="w-full" placeholder="Lucas" />
+            </UFormField>
+            <UFormField label="Role" required>
+              <UInput v-model="draft.role" class="w-full" placeholder="Market & Competitive Intelligence Analyst" />
+            </UFormField>
+            <UFormField label="Department" required>
+              <USelect v-model="draft.department" :items="departmentOptions" class="w-full" />
+            </UFormField>
+            <UFormField label="Tier">
+              <USelect v-model="draft.tier" :items="tierOptions" class="w-full" />
+            </UFormField>
+          </div>
+        </section>
+
+        <section class="space-y-3">
+          <h3 class="text-sm font-semibold uppercase tracking-wide text-muted">Behavioural DNA</h3>
+          <div class="grid grid-cols-2 md:grid-cols-4 gap-3">
+            <UFormField label="DISC primary">
+              <USelect v-model="draft.disc_primary" :items="discOptions" class="w-full" />
+            </UFormField>
+            <UFormField label="DISC secondary">
+              <USelect v-model="draft.disc_secondary" :items="discOptions" class="w-full" />
+            </UFormField>
+            <UFormField label="Enneagram type">
+              <UInput v-model.number="draft.enneagram_type" type="number" :min="1" :max="9" class="w-full" />
+            </UFormField>
+            <UFormField label="Enneagram wing">
+              <UInput v-model.number="draft.enneagram_wing" type="number" :min="1" :max="9" class="w-full" />
+            </UFormField>
+            <UFormField label="MBTI">
+              <USelect v-model="draft.mbti" :items="mbtiOptions" class="w-full" />
+            </UFormField>
+          </div>
+          <p v-if="draft.disc_primary === draft.disc_secondary" class="text-xs text-error">
+            DISC primary and secondary must differ.
+          </p>
+          <div class="space-y-2">
+            <p class="text-sm font-semibold text-muted">Big Five (OCEAN)</p>
+            <div v-for="key in bigFiveKeys" :key="key" class="flex items-center gap-3">
+              <span class="w-40 text-sm text-muted">{{ bigFiveLabels[key] }}</span>
+              <UInput
+                v-model.number="draft.big_five[key]"
+                type="number"
+                :min="0"
+                :max="100"
+                class="w-20"
+              />
+              <div class="flex-1 h-2 rounded-full bg-muted/20">
+                <div class="h-2 rounded-full bg-primary" :style="{ width: `${draft.big_five[key]}%` }" />
+              </div>
+            </div>
+          </div>
+        </section>
+
+        <section class="space-y-3">
+          <h3 class="text-sm font-semibold uppercase tracking-wide text-muted">Knowledge</h3>
+          <UFormField label="Mental models (primary)" help="comma-separated">
+            <template #hint>
+              <UButton
+                label="Suggest with AI"
+                icon="i-lucide-sparkles"
+                size="xs"
+                color="primary"
+                variant="soft"
+                :loading="suggestingField === 'mental_models'"
+                :disabled="suggestingField !== null"
+                @click="suggest('mental_models')"
+              />
+            </template>
+            <UInput
+              :model-value="listToCsv(draft.mental_models_primary)"
+              @update:model-value="(v: string) => { draft.mental_models_primary = csvToList(v) }"
+              class="w-full"
+            />
+          </UFormField>
+          <UFormField label="Expertise domains" help="comma-separated">
+            <template #hint>
+              <UButton
+                label="Suggest with AI"
+                icon="i-lucide-sparkles"
+                size="xs"
+                color="primary"
+                variant="soft"
+                :loading="suggestingField === 'expertise_domains'"
+                :disabled="suggestingField !== null"
+                @click="suggest('expertise_domains')"
+              />
+            </template>
+            <UInput
+              :model-value="listToCsv(draft.expertise_domains)"
+              @update:model-value="(v: string) => { draft.expertise_domains = csvToList(v) }"
+              class="w-full"
+            />
+          </UFormField>
+          <div class="grid grid-cols-2 gap-3">
+            <UFormField label="Depth">
+              <USelect v-model="draft.expertise_depth" :items="depthOptions" class="w-full" />
+            </UFormField>
+            <UFormField label="Years (equivalent)">
+              <UInput v-model.number="draft.expertise_years" type="number" :min="0" :max="60" class="w-full" />
+            </UFormField>
+          </div>
+          <UFormField label="Frameworks" help="comma-separated">
+            <template #hint>
+              <UButton
+                label="Suggest with AI"
+                icon="i-lucide-sparkles"
+                size="xs"
+                color="primary"
+                variant="soft"
+                :loading="suggestingField === 'frameworks'"
+                :disabled="suggestingField !== null"
+                @click="suggest('frameworks')"
+              />
+            </template>
+            <UInput
+              :model-value="listToCsv(draft.frameworks)"
+              @update:model-value="(v: string) => { draft.frameworks = csvToList(v) }"
+              class="w-full"
+            />
+          </UFormField>
+        </section>
+
+        <section class="space-y-3">
+          <h3 class="text-sm font-semibold uppercase tracking-wide text-muted">Communication</h3>
+          <div class="grid grid-cols-1 md:grid-cols-2 gap-3">
+            <UFormField label="Tone">
+              <UInput v-model="draft.comm_tone" class="w-full" placeholder="Analytical, calm" />
+            </UFormField>
+            <UFormField label="Vocabulary level">
+              <USelect v-model="draft.comm_vocab" :items="vocabOptions" class="w-full" />
+            </UFormField>
+            <UFormField label="Preferred format">
+              <UInput v-model="draft.comm_format" class="w-full" placeholder="Briefs, tables, charts" />
+            </UFormField>
+            <UFormField label="Language">
+              <UInput v-model="draft.comm_language" class="w-full" placeholder="en" />
+            </UFormField>
+          </div>
+          <UFormField label="Avoid (phrases)" help="comma-separated">
+            <UInput
+              :model-value="listToCsv(draft.comm_avoid)"
+              @update:model-value="(v: string) => { draft.comm_avoid = csvToList(v) }"
+              class="w-full"
+            />
+          </UFormField>
+        </section>
+
+        <section class="space-y-3">
+          <h3 class="text-sm font-semibold uppercase tracking-wide text-muted">Linked personas</h3>
+          <USelectMenu
+            v-model="draft.linked_personas"
+            :items="personaOptions"
+            value-key="value"
+            multiple
+            placeholder="Select personas to link"
+            class="w-full"
+          />
+        </section>
+
+        <div class="flex items-center justify-end gap-2 pt-4 border-t border-default">
+          <UButton label="Cancel" variant="ghost" :disabled="saving" to="/agents" />
+          <UButton
+            label="Create agent"
+            icon="i-lucide-check"
+            :loading="saving"
+            :disabled="!canSave"
+            @click="save"
+          />
+        </div>
+      </div>
+    </template>
+  </UDashboardPanel>
+</template>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.99.0",
+  "version": "3.1.0",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.99.0"
+version = "3.1.0"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}

package/scripts/dashboard-api.py

@@ -1683,6 +1683,186 @@ def metrics():
     return {"entries": entries[-50:], "avg_ms": round(avg_ms, 1), "total_calls": len(entries)}
 
 
+# --- Agent create (PR82 v3.0.0) ---
+
+@app.post("/api/agents")
+def agent_create(body: dict):
+    """Create a new agent YAML file from a manual draft.
+
+    Required body keys: name, role, department, tier.
+    Optional: behavioral_dna, expertise, mental_models, communication,
+    linked_personas, authority.
+
+    Slug rule: <name-kebab>-<random-suffix> when no explicit `id` is
+    given. The endpoint refuses to overwrite an existing file.
+    """
+    if not isinstance(body, dict):
+        return {"error": "body must be an object"}
+    return _do_agent_create(body)
+
+
+def _do_agent_create(body: dict) -> dict:
+    import re
+    import uuid
+
+    name = (body.get("name") or "").strip()
+    role = (body.get("role") or "").strip()
+    department = (body.get("department") or "").strip().lower()
+    tier_raw = body.get("tier")
+    if not name or not role or not department:
+        return {"error": "name, role, and department are required"}
+    try:
+        tier = int(tier_raw) if tier_raw is not None else 2
+    except (TypeError, ValueError):
+        return {"error": "tier must be an integer"}
+
+    dept_dir = ARKAOS_ROOT / "departments" / department / "agents"
+    if not dept_dir.exists():
+        return {"error": f"department '{department}' not found"}
+
+    explicit_id = (body.get("id") or "").strip()
+    if explicit_id:
+        slug = _agent_slugify(explicit_id)
+    else:
+        slug = f"{_agent_slugify(name)}-{uuid.uuid4().hex[:6]}"
+    yaml_file = dept_dir / f"{slug}.yaml"
+    if yaml_file.exists():
+        return {"error": f"agent with id '{slug}' already exists"}
+
+    try:
+        import yaml as _yaml
+    except ImportError:
+        return {"error": "PyYAML unavailable"}
+
+    payload = _build_agent_yaml(slug, name, role, department, tier, body)
+    try:
+        tmp = yaml_file.with_suffix(yaml_file.suffix + ".tmp")
+        tmp.write_text(
+            _yaml.safe_dump(payload, sort_keys=False, allow_unicode=True, default_flow_style=False),
+            encoding="utf-8",
+        )
+        tmp.replace(yaml_file)
+    except OSError as exc:
+        return {"error": f"write failed: {exc}"}
+    return {"id": slug, "created": True, "yaml_path": str(yaml_file)}
+
+
+def _agent_slugify(text: str) -> str:
+    import re
+    cleaned = re.sub(r"[^a-z0-9-]+", "-", text.lower())
+    cleaned = re.sub(r"-+", "-", cleaned).strip("-")
+    return cleaned or "agent"
+
+
+def _build_agent_yaml(
+    slug: str, name: str, role: str, department: str, tier: int, body: dict,
+) -> dict:
+    """Compose the YAML payload, applying sensible defaults."""
+    dna = body.get("behavioral_dna") or {}
+    disc = dna.get("disc") or {}
+    enneagram = dna.get("enneagram") or {}
+    big_five = dna.get("big_five") or {}
+    mbti_raw = dna.get("mbti")
+    mbti = mbti_raw.get("type") if isinstance(mbti_raw, dict) else mbti_raw
+
+    expertise = body.get("expertise") or {}
+    mental_models = body.get("mental_models") or {}
+    communication = body.get("communication") or {}
+    authority = body.get("authority") or {}
+
+    payload: dict = {
+        "id": slug,
+        "name": name,
+        "role": role,
+        "department": department,
+        "tier": tier,
+        "model": "opus" if tier == 0 else "sonnet",
+        "behavioral_dna": {
+            "disc": {
+                "primary": (disc.get("primary") or "I").upper(),
+                "secondary": (disc.get("secondary") or "S").upper(),
+                "communication_style": disc.get("communication_style") or "",
+                "under_pressure": disc.get("under_pressure") or "",
+                "motivator": disc.get("motivator") or "",
+            },
+            "enneagram": {
+                "type": int(enneagram.get("type") or 5),
+                "wing": int(enneagram.get("wing") or 4),
+                "core_motivation": enneagram.get("core_motivation") or "",
+                "core_fear": enneagram.get("core_fear") or "",
+                "subtype": enneagram.get("subtype") or "self-preservation",
+            },
+            "big_five": {
+                "openness": int(big_five.get("openness") or 70),
+                "conscientiousness": int(big_five.get("conscientiousness") or 70),
+                "extraversion": int(big_five.get("extraversion") or 50),
+                "agreeableness": int(big_five.get("agreeableness") or 60),
+                "neuroticism": int(big_five.get("neuroticism") or 30),
+            },
+            "mbti": {"type": (mbti or "INTJ").upper()},
+        },
+        "authority": {
+            "delegates_to": _agent_str_list(authority.get("delegates_to") or []),
+            "escalates_to": authority.get("escalates_to") or "",
+        },
+        "expertise": {
+            "domains": _agent_str_list(expertise.get("domains") or []),
+            "frameworks": _agent_str_list(expertise.get("frameworks") or []),
+            "depth": expertise.get("depth") or "advanced",
+            "years_equivalent": int(expertise.get("years_equivalent") or 5),
+        },
+        "mental_models": {
+            "primary": _agent_str_list(mental_models.get("primary") or []),
+            "secondary": _agent_str_list(mental_models.get("secondary") or []),
+        },
+        "communication": {
+            "tone": communication.get("tone") or "",
+            "vocabulary_level": communication.get("vocabulary_level") or "specialist",
+            "preferred_format": communication.get("preferred_format") or "",
+            "language": communication.get("language") or "en",
+            "avoid": _agent_str_list(communication.get("avoid") or []),
+        },
+        "linked_personas": _agent_str_list(body.get("linked_personas") or []),
+    }
+    return payload
+
+
+# --- AI agent draft from description (PR82b v3.1.0) ---
+
+@app.post("/api/agents/draft")
+def agents_draft(body: dict):
+    """Generate a full agent draft from a free-text description.
+
+    Body: {
+        "description": "...",   # min 20 chars
+        "name": "Lucas",         # optional
+        "role": "Market Analyst",# optional
+        "department": "strategy",# optional
+        "tier": 2                # optional, default 2
+    }
+    Returns: {"draft": {...behavioral_dna, expertise, mental_models,
+    communication...}, "provider_name": "..."}
+    """
+    from core.agents.draft_builder import DraftError, draft_agent
+
+    description = (body.get("description") or "").strip()
+    try:
+        tier = int(body.get("tier") or 2)
+    except (TypeError, ValueError):
+        tier = 2
+    try:
+        res = draft_agent(
+            description,
+            name=(body.get("name") or "").strip(),
+            role=(body.get("role") or "").strip(),
+            department=(body.get("department") or "").strip(),
+            tier=tier,
+        )
+    except DraftError as exc:
+        return {"error": str(exc)}
+    return {"draft": res.draft, "provider_name": res.provider_name}
+
+
 # --- AI list-field suggester (PR81 v2.99.0) ---
 
 @app.post("/api/agents/suggest")