arkaos 3.4.0 → 3.6.0

package/VERSION

@@ -1 +1 @@
-3.4.0
+3.6.0

package/core/agents/string_suggester.py

@@ -0,0 +1,111 @@
+"""AI-assisted single-string suggester (PR83c v3.5.0).
+
+Sibling to `core/agents/field_suggester` but for fields that hold ONE
+string value (not a list). Used by the ✨ Generate button next to
+fields like `communication.tone`, `communication.preferred_format`,
+and `communication.language`.
+
+Where the list suggester APPENDS, this one REPLACES. The caller is
+expected to swap the field's existing value with the result.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+from core.runtime.llm_provider import LLMProvider, LLMUnavailable, get_llm_provider
+
+
+_VALID_FIELDS: tuple[str, ...] = ("tone", "preferred_format", "language")
+
+_SYSTEM = (
+    "You suggest concise single-string values for behavioural agent and "
+    "persona profile fields. Return ONLY the value as plain text — no "
+    "JSON, no fences, no quotes, no explanations."
+)
+
+_FIELD_HINTS: dict[str, str] = {
+    "tone": (
+        "Return 2-4 adjectives separated by commas describing the "
+        "profile's voice (e.g. 'Direct, analytical, crisp'). "
+        "Max 60 characters."
+    ),
+    "preferred_format": (
+        "Return a short noun phrase listing the formats this profile "
+        "prefers (e.g. 'Briefs, tables, ASCII diagrams'). Max 80 characters."
+    ),
+    "language": (
+        "Return a comma-separated list of IETF language tags this profile "
+        "writes in (e.g. 'en' or 'en, pt-PT'). Max 20 characters."
+    ),
+}
+
+_MAX_LEN: dict[str, int] = {"tone": 60, "preferred_format": 80, "language": 20}
+
+
+class StringSuggestionError(RuntimeError):
+    """LLM produced unusable output or could not be reached."""
+
+
+@dataclass(frozen=True)
+class StringSuggestionResult:
+    value: str
+    provider_name: str
+
+
+def suggest_string_field(
+    field: str,
+    context: dict,
+    *,
+    provider: LLMProvider | None = None,
+) -> StringSuggestionResult:
+    """Return an AI-suggested single-string value for `field`."""
+    if field not in _VALID_FIELDS:
+        raise StringSuggestionError(f"unknown field: {field!r}")
+    llm = provider or get_llm_provider()
+    prompt = _build_prompt(field, context)
+    try:
+        resp = llm.complete(prompt, max_tokens=200, system=_SYSTEM)
+    except LLMUnavailable as exc:
+        raise StringSuggestionError(str(exc)) from exc
+    value = _clean(resp.text, field)
+    if not value:
+        raise StringSuggestionError("LLM returned an empty value")
+    return StringSuggestionResult(value=value, provider_name=llm.name())
+
+
+def _build_prompt(field: str, context: dict) -> str:
+    name = (context.get("name") or "").strip() or "the entity"
+    role = (context.get("role") or context.get("title") or "").strip()
+    department = (context.get("department") or "").strip()
+    current = (context.get("current") or "").strip()
+    lines = [f"Suggest a {field.replace('_', ' ')} for {name}."]
+    if role:
+        lines.append(f"Role: {role}.")
+    if department:
+        lines.append(f"Department: {department}.")
+    if current:
+        lines.append(f"Current value (to be replaced, do not repeat verbatim): {current}.")
+    lines.append(_FIELD_HINTS[field])
+    return "\n".join(lines)
+
+
+def _clean(text: str, field: str) -> str:
+    """Strip fences, quotes, leading bullets and trim to the field's max."""
+    cleaned = text.strip()
+    cleaned = re.sub(r"^```(?:\w+)?\s*|\s*```$", "", cleaned, flags=re.MULTILINE)
+    cleaned = cleaned.strip()
+    # Remove surrounding quotes the LLM may add.
+    if len(cleaned) >= 2 and cleaned[0] in '"\'`' and cleaned[-1] == cleaned[0]:
+        cleaned = cleaned[1:-1].strip()
+    # Drop a leading bullet/numbering.
+    cleaned = re.sub(r"^[-*•·]\s+", "", cleaned)
+    cleaned = re.sub(r"^\d+[.)]\s+", "", cleaned)
+    # Single-line: collapse internal whitespace, drop trailing punctuation.
+    cleaned = " ".join(cleaned.split())
+    cleaned = cleaned.rstrip(".")
+    max_len = _MAX_LEN[field]
+    if len(cleaned) > max_len:
+        cleaned = cleaned[:max_len].rstrip(", ").rstrip()
+    return cleaned

package/dashboard/app/components/AgentEditDrawer.vue

@@ -115,6 +115,52 @@ function csvToList(value: string): string[] {
 type SuggestField = 'mental_models_primary' | 'frameworks' | 'expertise_domains' | 'communication_avoid'
 const suggestingField = ref<SuggestField | null>(null)
 
+// PR83c v3.5.0 — single-string suggester.
+type StringField = 'tone' | 'preferred_format'
+const suggestingString = ref<StringField | null>(null)
+
+async function suggestString(field: StringField) {
+  if (!draft.value || !props.agent) return
+  const current
+    = field === 'tone' ? draft.value.communication.tone : draft.value.communication.preferred_format
+  suggestingString.value = field
+  try {
+    const res = await $fetch<{ value: string, provider_name: string, error?: string }>(
+      `${apiBase}/api/agents/suggest-string`,
+      {
+        method: 'POST',
+        body: {
+          field,
+          context: {
+            name: props.agent.name,
+            role: props.agent.role,
+            department: props.agent.department,
+            current,
+          },
+        },
+      },
+    )
+    if (res.error) throw new Error(res.error)
+    if (field === 'tone') draft.value.communication.tone = res.value
+    else draft.value.communication.preferred_format = res.value
+    markDirty()
+    toast.add({
+      title: 'Generated',
+      description: `via ${res.provider_name}`,
+      color: 'success',
+      icon: 'i-lucide-sparkles',
+    })
+  } catch (err) {
+    toast.add({
+      title: 'Generate failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    suggestingString.value = null
+  }
+}
+
 async function suggest(field: SuggestField) {
   if (!draft.value || !props.agent) return
   const backendField = field === 'mental_models_primary' ? 'mental_models' : field
@@ -424,6 +470,18 @@ const vocabOptions = [
             <h3 class="text-xs font-semibold uppercase tracking-wider text-muted">Communication</h3>
             <div class="grid grid-cols-1 md:grid-cols-2 gap-3">
               <UFormField label="Tone">
+                <template #hint>
+                  <UButton
+                    label="Generate"
+                    icon="i-lucide-sparkles"
+                    size="xs"
+                    color="primary"
+                    variant="soft"
+                    :loading="suggestingString === 'tone'"
+                    :disabled="suggestingString !== null"
+                    @click="suggestString('tone')"
+                  />
+                </template>
                 <UInput v-model="draft.communication.tone" class="w-full" @update:model-value="markDirty" />
               </UFormField>
               <UFormField label="Vocabulary level">
@@ -435,6 +493,18 @@ const vocabOptions = [
                 />
               </UFormField>
               <UFormField label="Preferred format">
+                <template #hint>
+                  <UButton
+                    label="Generate"
+                    icon="i-lucide-sparkles"
+                    size="xs"
+                    color="primary"
+                    variant="soft"
+                    :loading="suggestingString === 'preferred_format'"
+                    :disabled="suggestingString !== null"
+                    @click="suggestString('preferred_format')"
+                  />
+                </template>
                 <UInput v-model="draft.communication.preferred_format" class="w-full" @update:model-value="markDirty" />
               </UFormField>
               <UFormField label="Language">

package/dashboard/app/pages/agents/[id].vue

@@ -27,6 +27,38 @@ const deptActivity = computed<ActivityRow | null>(() =>
   (activityData.value?.by_department?.[agent.value?.department ?? ''] ?? null),
 )
 
+// PR83d v3.6.0 — activity strip (30d, dept-level + last_used + rank)
+interface ActivityStrip {
+  period: string
+  department: string
+  calls: number
+  cost_usd: number | null
+  tokens_in: number
+  tokens_out: number
+  last_used: string | null
+  dept_rank: number | null
+  dept_count: number
+}
+const { data: activityStrip } = fetchApi<ActivityStrip>(
+  `/api/agents/${agentId}/activity-strip?period=month`,
+)
+
+function formatRelative(iso: string | null): string {
+  if (!iso) return 'never'
+  const ts = Date.parse(iso)
+  if (Number.isNaN(ts)) return 'never'
+  const diff = Date.now() - ts
+  const minutes = Math.floor(diff / 60_000)
+  if (minutes < 1) return 'just now'
+  if (minutes < 60) return `${minutes}m ago`
+  const hours = Math.floor(minutes / 60)
+  if (hours < 24) return `${hours}h ago`
+  const days = Math.floor(hours / 24)
+  if (days < 30) return `${days}d ago`
+  const months = Math.floor(days / 30)
+  return `${months}mo ago`
+}
+
 // PR76 — edit drawer state
 const editOpen = ref(false)
 
@@ -291,6 +323,49 @@ function formatTokens(n: number): string {
           </div>
         </section>
 
+        <!-- ===== ACTIVITY STRIP (PR83d) ===== -->
+        <section
+          v-if="activityStrip"
+          class="rounded-xl border border-default bg-elevated/10 p-4"
+        >
+          <div class="flex flex-wrap items-center gap-x-6 gap-y-3 text-sm">
+            <div class="flex items-center gap-2">
+              <UIcon name="i-lucide-activity" class="size-4 text-primary" />
+              <span class="font-semibold uppercase tracking-wide text-muted text-xs">
+                30d activity (dept)
+              </span>
+            </div>
+            <div class="flex items-center gap-2">
+              <span class="text-muted">Calls</span>
+              <span class="font-mono font-semibold">{{ activityStrip.calls }}</span>
+            </div>
+            <div class="flex items-center gap-2">
+              <span class="text-muted">Cost</span>
+              <span class="font-mono font-semibold">{{ formatCost(activityStrip.cost_usd) }}</span>
+            </div>
+            <div class="flex items-center gap-2">
+              <span class="text-muted">Tokens</span>
+              <span class="font-mono">
+                {{ formatTokens(activityStrip.tokens_in) }} /
+                {{ formatTokens(activityStrip.tokens_out) }}
+              </span>
+            </div>
+            <div class="flex items-center gap-2">
+              <span class="text-muted">Last used</span>
+              <span class="font-mono">{{ formatRelative(activityStrip.last_used) }}</span>
+            </div>
+            <div v-if="activityStrip.dept_rank" class="flex items-center gap-2">
+              <span class="text-muted">Dept rank</span>
+              <UBadge
+                :label="`#${activityStrip.dept_rank} of ${activityStrip.dept_count}`"
+                :color="activityStrip.dept_rank <= 3 ? 'primary' : 'neutral'"
+                variant="subtle"
+                size="sm"
+              />
+            </div>
+          </div>
+        </section>
+
         <AgentEditDrawer
           v-model="editOpen"
           :agent="agent"

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

@@ -88,6 +88,56 @@ const draft = ref<AgentDraft>({
 
 const saving = ref(false)
 
+// PR83c v3.5.0 — single-string suggester.
+type StringField = 'tone' | 'preferred_format'
+const suggestingString = ref<StringField | null>(null)
+
+async function suggestString(field: StringField) {
+  if (!draft.value.name.trim() || !draft.value.role.trim()) {
+    toast.add({
+      title: 'Add a name and role first',
+      color: 'warning',
+    })
+    return
+  }
+  const current = field === 'tone' ? draft.value.comm_tone : draft.value.comm_format
+  suggestingString.value = field
+  try {
+    const res = await $fetch<{ value: string, provider_name: string, error?: string }>(
+      `${apiBase}/api/agents/suggest-string`,
+      {
+        method: 'POST',
+        body: {
+          field,
+          context: {
+            name: draft.value.name,
+            role: draft.value.role,
+            department: draft.value.department,
+            current,
+          },
+        },
+      },
+    )
+    if (res.error) throw new Error(res.error)
+    if (field === 'tone') draft.value.comm_tone = res.value
+    else draft.value.comm_format = res.value
+    toast.add({
+      title: 'Generated',
+      description: `via ${res.provider_name}`,
+      color: 'success',
+      icon: 'i-lucide-sparkles',
+    })
+  } catch (err) {
+    toast.add({
+      title: 'Generate failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    suggestingString.value = null
+  }
+}
+
 // PR82b v3.1.0 — AI draft from description.
 const description = ref('')
 const drafting = ref(false)
@@ -544,12 +594,36 @@ const bigFiveKeys = ['openness', 'conscientiousness', 'extraversion', 'agreeable
           <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">
+              <template #hint>
+                <UButton
+                  label="Generate"
+                  icon="i-lucide-sparkles"
+                  size="xs"
+                  color="primary"
+                  variant="soft"
+                  :loading="suggestingString === 'tone'"
+                  :disabled="suggestingString !== null"
+                  @click="suggestString('tone')"
+                />
+              </template>
               <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">
+              <template #hint>
+                <UButton
+                  label="Generate"
+                  icon="i-lucide-sparkles"
+                  size="xs"
+                  color="primary"
+                  variant="soft"
+                  :loading="suggestingString === 'preferred_format'"
+                  :disabled="suggestingString !== null"
+                  @click="suggestString('preferred_format')"
+                />
+              </template>
               <UInput v-model="draft.comm_format" class="w-full" placeholder="Briefs, tables, charts" />
             </UFormField>
             <UFormField label="Language">

package/dashboard/app/pages/personas/[id].vue

@@ -226,6 +226,48 @@ function csvToList(value: string): string[] {
 type SuggestField = 'mental_models' | 'frameworks' | 'expertise_domains' | 'communication_avoid' | 'key_quotes'
 const suggestingField = ref<SuggestField | null>(null)
 
+// PR83c v3.5.0 — single-string suggester (tone for personas).
+const suggestingString = ref<'tone' | null>(null)
+
+async function suggestString(field: 'tone') {
+  if (!draft.value || !detail.value) return
+  const current = draft.value.communication.tone
+  suggestingString.value = field
+  try {
+    const res = await $fetch<{ value: string, provider_name: string, error?: string }>(
+      `${apiBase}/api/personas/suggest-string`,
+      {
+        method: 'POST',
+        body: {
+          field,
+          context: {
+            name: detail.value.name,
+            title: detail.value.title,
+            current,
+          },
+        },
+      },
+    )
+    if (res.error) throw new Error(res.error)
+    draft.value.communication.tone = res.value
+    markDirty()
+    toast.add({
+      title: 'Generated',
+      description: `via ${res.provider_name}`,
+      color: 'success',
+      icon: 'i-lucide-sparkles',
+    })
+  } catch (err) {
+    toast.add({
+      title: 'Generate failed',
+      description: err instanceof Error ? err.message : 'unknown error',
+      color: 'error',
+    })
+  } finally {
+    suggestingString.value = null
+  }
+}
+
 async function suggest(field: SuggestField) {
   if (!draft.value || !detail.value) return
   const current
@@ -754,6 +796,18 @@ const vocabOptions = [
                     <h3 class="text-xs font-semibold uppercase tracking-wider text-muted">Communication</h3>
                     <div class="grid grid-cols-1 md:grid-cols-2 gap-3">
                       <UFormField label="Tone">
+                        <template #hint>
+                          <UButton
+                            label="Generate"
+                            icon="i-lucide-sparkles"
+                            size="xs"
+                            color="primary"
+                            variant="soft"
+                            :loading="suggestingString === 'tone'"
+                            :disabled="suggestingString !== null"
+                            @click="suggestString('tone')"
+                          />
+                        </template>
                         <UInput v-model="draft.communication.tone" class="w-full" @update:model-value="markDirty" />
                       </UFormField>
                       <UFormField label="Vocabulary level">

package/package.json

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

package/pyproject.toml

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

package/scripts/dashboard-api.py

@@ -218,6 +218,90 @@ def agents_activity(period: str = "week"):
     return {"by_department": out, "period": period}
 
 
+@app.get("/api/agents/{agent_id}/activity-strip")
+def agent_activity_strip(agent_id: str, period: str = "month"):
+    """PR83d v3.6.0 — compact activity payload for the agent hero strip.
+
+    Returns:
+      {
+        "period": "month",
+        "department": "<dept>",
+        "calls": <int>,
+        "cost_usd": <float|null>,
+        "tokens_in": <int>, "tokens_out": <int>,
+        "last_used": "<ISO ts>"|null,
+        "dept_rank": <1-based int>|null,
+        "dept_count": <int>
+      }
+
+    All values reflect the agent's DEPARTMENT (per-agent attribution
+    isn't tracked yet — see PR47 telemetry).
+    """
+    agents = _load_agents()
+    base = None
+    for a in agents:
+        if a.get("id") == agent_id:
+            base = dict(a)
+            break
+    if not base:
+        return {"error": "Agent not found"}
+    dept = base.get("department") or ""
+    try:
+        from core.runtime.llm_cost_telemetry import (
+            VALID_PERIODS,
+            _load_slice,
+            _period_cutoff,
+            summarise,
+        )
+    except Exception:
+        return {"error": "telemetry unavailable"}
+    if period not in VALID_PERIODS:
+        period = "month"
+
+    summary = summarise(period=period)
+    dept_costs: list[tuple[str, float]] = []
+    target_row: dict | None = None
+    for category, row in (summary.by_category or {}).items():
+        if not isinstance(category, str) or not category.startswith("subagent:"):
+            continue
+        cat_dept = category.split(":", 1)[1] or "unknown"
+        cost = row.get("total_cost_usd")
+        dept_costs.append((cat_dept, float(cost) if isinstance(cost, (int, float)) else 0.0))
+        if cat_dept == dept:
+            target_row = row
+
+    dept_costs.sort(key=lambda t: t[1], reverse=True)
+    dept_rank: Optional[int] = None
+    for idx, (d, _) in enumerate(dept_costs, start=1):
+        if d == dept:
+            dept_rank = idx
+            break
+
+    entries, _ = _load_slice(None, _period_cutoff(period, now=None))
+    last_used: Optional[str] = None
+    for entry in reversed(entries):
+        cat = entry.get("category") or ""
+        if isinstance(cat, str) and cat == f"subagent:{dept}":
+            last_used = entry.get("ts")
+            break
+
+    return {
+        "period": period,
+        "department": dept,
+        "calls": int(target_row.get("call_count", 0)) if target_row else 0,
+        "cost_usd": (
+            float(target_row.get("total_cost_usd"))
+            if target_row and isinstance(target_row.get("total_cost_usd"), (int, float))
+            else None
+        ),
+        "tokens_in": int(target_row.get("total_tokens_in", 0)) if target_row else 0,
+        "tokens_out": int(target_row.get("total_tokens_out", 0)) if target_row else 0,
+        "last_used": last_used,
+        "dept_rank": dept_rank,
+        "dept_count": len(dept_costs),
+    }
+
+
 @app.get("/api/agents/{agent_id}")
 def agent_detail(agent_id: str):
     """Get full agent detail including YAML data."""
@@ -1949,6 +2033,33 @@ def agents_draft(body: dict):
     return {"draft": res.draft, "provider_name": res.provider_name}
 
 
+# --- AI single-string suggester (PR83c v3.5.0) ---
+
+@app.post("/api/agents/suggest-string")
+def agents_suggest_string(body: dict):
+    """Suggest a single-string value (tone, preferred_format, language)."""
+    return _do_string_suggest(body, source="agent")
+
+
+@app.post("/api/personas/suggest-string")
+def personas_suggest_string(body: dict):
+    return _do_string_suggest(body, source="persona")
+
+
+def _do_string_suggest(body: dict, *, source: str) -> dict:
+    from core.agents.string_suggester import (
+        StringSuggestionError,
+        suggest_string_field,
+    )
+    field = (body.get("field") or "").strip()
+    context = body.get("context") or {}
+    try:
+        res = suggest_string_field(field, context)
+    except StringSuggestionError as exc:
+        return {"error": str(exc)}
+    return {"value": res.value, "provider_name": res.provider_name, "source": source}
+
+
 # --- AI list-field suggester (PR81 v2.99.0) ---
 
 @app.post("/api/agents/suggest")