@pellux/goodvibes-agent 0.1.2 → 0.1.3

package/src/agent/skill-registry.ts

@@ -0,0 +1,360 @@
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import type { ShellPathService } from '@/runtime/index.ts';
+import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
+import { assertNoSecretLikeText } from './persona-registry.ts';
+
+export type AgentSkillSource = 'user' | 'agent' | 'imported' | 'system';
+export type AgentSkillReviewState = 'fresh' | 'reviewed' | 'stale';
+
+export interface AgentSkillRecord {
+  readonly id: string;
+  readonly name: string;
+  readonly description: string;
+  readonly procedure: string;
+  readonly triggers: readonly string[];
+  readonly tags: readonly string[];
+  readonly enabled: boolean;
+  readonly source: AgentSkillSource;
+  readonly provenance: string;
+  readonly reviewState: AgentSkillReviewState;
+  readonly staleReason?: string;
+  readonly createdAt: string;
+  readonly updatedAt: string;
+  readonly reviewedAt?: string;
+}
+
+export interface AgentSkillCreateInput {
+  readonly name: string;
+  readonly description: string;
+  readonly procedure: string;
+  readonly triggers?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly enabled?: boolean;
+  readonly source?: AgentSkillSource;
+  readonly provenance?: string;
+}
+
+export interface AgentSkillUpdateInput {
+  readonly name?: string;
+  readonly description?: string;
+  readonly procedure?: string;
+  readonly triggers?: readonly string[];
+  readonly tags?: readonly string[];
+  readonly provenance?: string;
+}
+
+export interface AgentSkillSnapshot {
+  readonly path: string;
+  readonly skills: readonly AgentSkillRecord[];
+  readonly enabledSkills: readonly AgentSkillRecord[];
+}
+
+interface SkillStoreFile {
+  readonly version: 1;
+  readonly skills: readonly AgentSkillRecord[];
+}
+
+const STORE_VERSION = 1;
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readString(value: unknown, fallback = ''): string {
+  return typeof value === 'string' ? value : fallback;
+}
+
+function readStringArray(value: unknown): string[] {
+  if (!Array.isArray(value)) return [];
+  return value.filter((entry): entry is string => typeof entry === 'string').map((entry) => entry.trim()).filter(Boolean);
+}
+
+function normalizeName(name: string): string {
+  return name.trim().replace(/\s+/g, ' ');
+}
+
+function normalizeList(values: readonly string[] | undefined): string[] {
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const value of values ?? []) {
+    const trimmed = value.trim();
+    if (!trimmed) continue;
+    const key = trimmed.toLowerCase();
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(trimmed);
+  }
+  return result;
+}
+
+function slugify(value: string): string {
+  const slug = value.trim().toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  return slug || 'skill';
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function parseSkill(value: unknown): AgentSkillRecord | null {
+  if (!isRecord(value)) return null;
+  const id = readString(value.id).trim();
+  const name = normalizeName(readString(value.name));
+  const description = readString(value.description).trim();
+  const procedure = readString(value.procedure).trim();
+  if (!id || !name || !description || !procedure) return null;
+  const reviewState = value.reviewState === 'reviewed' || value.reviewState === 'stale' ? value.reviewState : 'fresh';
+  const source = value.source === 'agent' || value.source === 'imported' || value.source === 'system' ? value.source : 'user';
+  const staleReason = readString(value.staleReason).trim();
+  const reviewedAt = readString(value.reviewedAt).trim();
+  return {
+    id,
+    name,
+    description,
+    procedure,
+    triggers: readStringArray(value.triggers),
+    tags: readStringArray(value.tags),
+    enabled: value.enabled === true,
+    source,
+    provenance: readString(value.provenance, source).trim() || source,
+    reviewState,
+    staleReason: staleReason || undefined,
+    createdAt: readString(value.createdAt, nowIso()),
+    updatedAt: readString(value.updatedAt, nowIso()),
+    reviewedAt: reviewedAt || undefined,
+  };
+}
+
+function parseStore(raw: string): SkillStoreFile {
+  const parsed: unknown = JSON.parse(raw);
+  if (!isRecord(parsed)) return { version: STORE_VERSION, skills: [] };
+  return {
+    version: STORE_VERSION,
+    skills: Array.isArray(parsed.skills)
+      ? parsed.skills.map(parseSkill).filter((entry): entry is AgentSkillRecord => entry !== null)
+      : [],
+  };
+}
+
+function formatStore(store: SkillStoreFile): string {
+  return `${JSON.stringify(store, null, 2)}\n`;
+}
+
+export function skillStorePath(shellPaths: ShellPathService): string {
+  return shellPaths.resolveUserPath(GOODVIBES_AGENT_SURFACE_ROOT, 'skills', 'skills.json');
+}
+
+export class AgentSkillRegistry {
+  public constructor(private readonly storePath: string) {}
+
+  public static fromShellPaths(shellPaths: ShellPathService): AgentSkillRegistry {
+    return new AgentSkillRegistry(skillStorePath(shellPaths));
+  }
+
+  public snapshot(): AgentSkillSnapshot {
+    const store = this.readStore();
+    return {
+      path: this.storePath,
+      skills: [...store.skills],
+      enabledSkills: store.skills.filter((skill) => skill.enabled),
+    };
+  }
+
+  public list(): readonly AgentSkillRecord[] {
+    return this.snapshot().skills;
+  }
+
+  public search(query: string): readonly AgentSkillRecord[] {
+    const normalized = query.trim().toLowerCase();
+    if (!normalized) return this.list();
+    return this.list().filter((skill) => [
+      skill.id,
+      skill.name,
+      skill.description,
+      skill.procedure,
+      ...skill.tags,
+      ...skill.triggers,
+    ].some((field) => field.toLowerCase().includes(normalized)));
+  }
+
+  public get(idOrName: string): AgentSkillRecord | null {
+    const lookup = idOrName.trim().toLowerCase();
+    if (!lookup) return null;
+    return this.list().find((skill) => skill.id.toLowerCase() === lookup || skill.name.toLowerCase() === lookup) ?? null;
+  }
+
+  public create(input: AgentSkillCreateInput): AgentSkillRecord {
+    const store = this.readStore();
+    const name = normalizeName(input.name);
+    const description = input.description.trim();
+    const procedure = input.procedure.trim();
+    this.validateRequired(name, description, procedure);
+    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? [])]);
+    const duplicate = store.skills.find((skill) => skill.name.toLowerCase() === name.toLowerCase());
+    if (duplicate) throw new Error(`Skill already exists: ${duplicate.id}`);
+    const timestamp = nowIso();
+    const skill: AgentSkillRecord = {
+      id: this.nextId(name, store.skills),
+      name,
+      description,
+      procedure,
+      triggers: normalizeList(input.triggers),
+      tags: normalizeList(input.tags),
+      enabled: input.enabled === true,
+      source: input.source ?? 'user',
+      provenance: input.provenance?.trim() || input.source || 'user',
+      reviewState: 'fresh',
+      createdAt: timestamp,
+      updatedAt: timestamp,
+    };
+    this.writeStore({ ...store, skills: [...store.skills, skill] });
+    return skill;
+  }
+
+  public update(idOrName: string, input: AgentSkillUpdateInput): AgentSkillRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrName);
+    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    const name = input.name === undefined ? existing.name : normalizeName(input.name);
+    const description = input.description === undefined ? existing.description : input.description.trim();
+    const procedure = input.procedure === undefined ? existing.procedure : input.procedure.trim();
+    this.validateRequired(name, description, procedure);
+    assertNoSecretLikeText([name, description, procedure, ...(input.tags ?? []), ...(input.triggers ?? [])]);
+    const duplicate = store.skills.find((skill) => skill.id !== existing.id && skill.name.toLowerCase() === name.toLowerCase());
+    if (duplicate) throw new Error(`Skill already exists: ${duplicate.id}`);
+    const updated: AgentSkillRecord = {
+      ...existing,
+      name,
+      description,
+      procedure,
+      triggers: input.triggers === undefined ? existing.triggers : normalizeList(input.triggers),
+      tags: input.tags === undefined ? existing.tags : normalizeList(input.tags),
+      provenance: input.provenance === undefined ? existing.provenance : input.provenance.trim() || existing.provenance,
+      reviewState: 'fresh',
+      staleReason: undefined,
+      reviewedAt: undefined,
+      updatedAt: nowIso(),
+    };
+    this.writeStore({
+      ...store,
+      skills: store.skills.map((skill) => skill.id === existing.id ? updated : skill),
+    });
+    return updated;
+  }
+
+  public setEnabled(idOrName: string, enabled: boolean): AgentSkillRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrName);
+    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    const updated: AgentSkillRecord = { ...existing, enabled, updatedAt: nowIso() };
+    this.writeStore({
+      ...store,
+      skills: store.skills.map((skill) => skill.id === existing.id ? updated : skill),
+    });
+    return updated;
+  }
+
+  public markReviewed(idOrName: string): AgentSkillRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrName);
+    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    const updated: AgentSkillRecord = {
+      ...existing,
+      reviewState: 'reviewed',
+      staleReason: undefined,
+      reviewedAt: nowIso(),
+      updatedAt: nowIso(),
+    };
+    this.writeStore({
+      ...store,
+      skills: store.skills.map((skill) => skill.id === existing.id ? updated : skill),
+    });
+    return updated;
+  }
+
+  public markStale(idOrName: string, reason: string): AgentSkillRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrName);
+    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    const updated: AgentSkillRecord = {
+      ...existing,
+      reviewState: 'stale',
+      staleReason: reason.trim() || 'Marked stale by user.',
+      updatedAt: nowIso(),
+    };
+    this.writeStore({
+      ...store,
+      skills: store.skills.map((skill) => skill.id === existing.id ? updated : skill),
+    });
+    return updated;
+  }
+
+  public deleteSkill(idOrName: string): AgentSkillRecord {
+    const store = this.readStore();
+    const existing = this.findInStore(store, idOrName);
+    if (!existing) throw new Error(`Unknown skill: ${idOrName}`);
+    this.writeStore({
+      ...store,
+      skills: store.skills.filter((skill) => skill.id !== existing.id),
+    });
+    return existing;
+  }
+
+  private validateRequired(name: string, description: string, procedure: string): void {
+    if (!name) throw new Error('Skill name is required.');
+    if (!description) throw new Error('Skill description is required.');
+    if (!procedure) throw new Error('Skill procedure is required.');
+  }
+
+  private nextId(name: string, skills: readonly AgentSkillRecord[]): string {
+    const base = slugify(name);
+    const ids = new Set(skills.map((skill) => skill.id));
+    if (!ids.has(base)) return base;
+    for (let index = 2; index < 1000; index += 1) {
+      const candidate = `${base}-${index}`;
+      if (!ids.has(candidate)) return candidate;
+    }
+    throw new Error(`Could not allocate skill id for ${name}.`);
+  }
+
+  private findInStore(store: SkillStoreFile, idOrName: string): AgentSkillRecord | null {
+    const lookup = idOrName.trim().toLowerCase();
+    if (!lookup) return null;
+    return store.skills.find((skill) => skill.id.toLowerCase() === lookup || skill.name.toLowerCase() === lookup) ?? null;
+  }
+
+  private readStore(): SkillStoreFile {
+    if (!existsSync(this.storePath)) return { version: STORE_VERSION, skills: [] };
+    try {
+      return parseStore(readFileSync(this.storePath, 'utf-8'));
+    } catch (error) {
+      throw new Error(`Could not read Agent skill store: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+
+  private writeStore(store: SkillStoreFile): void {
+    mkdirSync(dirname(this.storePath), { recursive: true });
+    const tmpPath = `${this.storePath}.tmp`;
+    writeFileSync(tmpPath, formatStore(store), 'utf-8');
+    renameSync(tmpPath, this.storePath);
+  }
+}
+
+export function buildEnabledSkillsPrompt(shellPaths: ShellPathService): string | null {
+  const enabled = AgentSkillRegistry.fromShellPaths(shellPaths).snapshot().enabledSkills;
+  if (enabled.length === 0) return null;
+  return [
+    '## Enabled GoodVibes Agent Skills',
+    'Use these local reusable procedures inside the same serial assistant conversation when they fit the user request.',
+    '',
+    ...enabled.slice(0, 8).flatMap((skill) => [
+      `### ${skill.name}`,
+      `Description: ${skill.description}`,
+      `Review state: ${skill.reviewState}`,
+      `Triggers: ${skill.triggers.join(', ') || '(manual)'}`,
+      skill.procedure,
+      '',
+    ]),
+  ].join('\n').trim();
+}

package/src/audio/spoken-turn-model-routing.ts

@@ -2,6 +2,7 @@ import type { ConfigManager } from '@pellux/goodvibes-sdk/platform/config';
 import type { ModelDefinition, ProviderRegistry } from '@pellux/goodvibes-sdk/platform/providers';
 import type { ContentPart } from '@pellux/goodvibes-sdk/platform/providers';
 import type { Orchestrator, OrchestratorUserInputOptions } from '../core/orchestrator.ts';
+import { GOODVIBES_AGENT_PAIRING_SURFACE } from '../config/surface.ts';
 
 const SPOKEN_TURN_SOURCE = 'tts';
 
@@ -27,7 +28,7 @@ export function createSpokenTurnInputOptions(): OrchestratorUserInputOptions {
   return {
     origin: {
       source: SPOKEN_TURN_SOURCE,
-      surface: 'tui',
+      surface: GOODVIBES_AGENT_PAIRING_SURFACE,
       metadata: { spokenOutput: true },
     },
   };

package/src/cli/management-commands.ts

@@ -11,6 +11,7 @@ import { resolveRuntimeEndpointBinding } from './endpoints.ts';
 import { classifyBindPosture, isNetworkFacing } from './network-posture.ts';
 import type { CliCommandRuntime } from './management.ts';
 import { extractAuthorizationCode, formatJsonOrText, hasCommandFlag, openBrowser, probeTcp, readAuthPaths, runNonInteractiveAgent, urlHostForBindHost, withRuntimeServices, yesNo } from './management.ts';
+import { GOODVIBES_AGENT_PAIRING_SURFACE } from '../config/surface.ts';
 
 export async function renderSubscriptions(runtime: CliCommandRuntime): Promise<string> {
   return await withRuntimeServices(runtime, async (services) => {
@@ -370,13 +371,14 @@ export async function renderControlPlaneStatus(runtime: CliCommandRuntime): Prom
 
 export async function renderPairing(runtime: CliCommandRuntime): Promise<string> {
   const daemonHomeDir = join(runtime.homeDirectory, '.goodvibes', 'daemon');
-  const tokenRecord = getOrCreateCompanionToken('tui', { daemonHomeDir });
+  const tokenRecord = getOrCreateCompanionToken(GOODVIBES_AGENT_PAIRING_SURFACE, { daemonHomeDir });
   const binding = resolveRuntimeEndpointBinding(runtime.configManager, 'controlPlane');
   const daemonUrl = `http://${urlHostForBindHost(binding.host)}:${binding.port}`;
   const info = buildCompanionConnectionInfo({
     daemonUrl,
     token: tokenRecord.token,
     username: 'admin',
+    surface: GOODVIBES_AGENT_PAIRING_SURFACE,
   });
   const payload = encodeConnectionPayload(info);
   const qr = renderQrToString(generateQrMatrix(payload));

package/src/config/surface.ts

@@ -1 +1,2 @@
 export const GOODVIBES_AGENT_SURFACE_ROOT = 'agent';
+export const GOODVIBES_AGENT_PAIRING_SURFACE = 'goodvibes-agent';

package/src/input/agent-workspace.ts

@@ -1,5 +1,7 @@
 import type { InputToken } from '@pellux/goodvibes-sdk/platform/core';
 import type { CommandContext } from './command-registry.ts';
+import { AgentPersonaRegistry } from '../agent/persona-registry.ts';
+import { AgentSkillRegistry } from '../agent/skill-registry.ts';
 
 export const AGENT_WORKSPACE_MODAL_NAME = 'agentWorkspace';
 
@@ -51,6 +53,10 @@ export interface AgentWorkspaceRuntimeSnapshot {
   readonly daemonBaseUrl: string;
   readonly daemonOwnership: 'external';
   readonly sessionMemoryCount: number;
+  readonly localSkillCount: number;
+  readonly enabledSkillCount: number;
+  readonly localPersonaCount: number;
+  readonly activePersonaName: string;
   readonly knowledgeRoute: '/api/goodvibes-agent/knowledge';
   readonly knowledgeIsolation: 'agent-only';
   readonly executionPolicy: 'serial-proactive';
@@ -98,6 +104,26 @@ export function buildAgentWorkspaceRuntimeSnapshot(context: CommandContext): Age
       return 0;
     }
   })();
+  const personaSnapshot = (() => {
+    try {
+      const shellPaths = context.workspace?.shellPaths;
+      if (!shellPaths) return { count: 0, activeName: '(none)' };
+      const snapshot = AgentPersonaRegistry.fromShellPaths(shellPaths).snapshot();
+      return { count: snapshot.personas.length, activeName: snapshot.activePersona?.name ?? '(none)' };
+    } catch {
+      return { count: 0, activeName: '(unavailable)' };
+    }
+  })();
+  const skillSnapshot = (() => {
+    try {
+      const shellPaths = context.workspace?.shellPaths;
+      if (!shellPaths) return { count: 0, enabled: 0 };
+      const snapshot = AgentSkillRegistry.fromShellPaths(shellPaths).snapshot();
+      return { count: snapshot.skills.length, enabled: snapshot.enabledSkills.length };
+    } catch {
+      return { count: 0, enabled: 0 };
+    }
+  })();
   const warnings: string[] = [];
   if (provider === 'unknown' || model === 'unknown') warnings.push('Provider/model unavailable in this runtime context.');
   if (!context.executeCommand) warnings.push('Command dispatch is unavailable; workspace actions will show guidance only.');
@@ -112,6 +138,10 @@ export function buildAgentWorkspaceRuntimeSnapshot(context: CommandContext): Age
     daemonBaseUrl: `http://${host}:${port}`,
     daemonOwnership: 'external',
     sessionMemoryCount,
+    localSkillCount: skillSnapshot.count,
+    enabledSkillCount: skillSnapshot.enabled,
+    localPersonaCount: personaSnapshot.count,
+    activePersonaName: personaSnapshot.activeName,
     knowledgeRoute: '/api/goodvibes-agent/knowledge',
     knowledgeIsolation: 'agent-only',
     executionPolicy: 'serial-proactive',
@@ -167,8 +197,8 @@ export const AGENT_WORKSPACE_CATEGORIES: readonly AgentWorkspaceCategory[] = [
     detail: 'Memory, skills, and personas stay Agent-local until stable shared daemon registry contracts exist. Secrets must not be stored as memory.',
     actions: [
       { id: 'memory', label: 'Open memory', detail: 'Inspect local/session memory commands and surfaces.', command: '/memory', kind: 'command', safety: 'read-only' },
-      { id: 'skills', label: 'Open skills', detail: 'Inspect discovered skills and skill catalog state.', command: '/skills open', kind: 'command', safety: 'read-only' },
-      { id: 'personas', label: 'Persona library', detail: 'Use local Agent personas to shape serial assistant behavior without spawning background agents.', kind: 'guidance', safety: 'safe' },
+      { id: 'skills', label: 'Local skill library', detail: 'Create, review, and enable local Agent reusable procedures.', command: '/agent-skills', kind: 'command', safety: 'safe' },
+      { id: 'personas', label: 'Persona library', detail: 'Use local Agent personas to shape serial assistant behavior without spawning background agents.', command: '/personas', kind: 'command', safety: 'safe' },
     ],
   },
   {

package/src/input/command-registry.ts

@@ -180,7 +180,9 @@ export interface CommandExtensionRegistryServices {
 
 export interface CommandExtensionServices
   extends CommandExtensionRegistryServices,
-    CommandExtensionShellServices {}
+    CommandExtensionShellServices {
+  readonly agentKnowledgeService?: import('@pellux/goodvibes-sdk/platform/knowledge').KnowledgeService;
+}
 
 /**
  * CommandContext - Passed to every slash command handler so commands can
@@ -200,6 +202,7 @@ export interface CommandContext
     readonly operator?: OperatorClient;
     readonly peer?: PeerClient;
     readonly providerApi?: ProviderApi;
+    readonly agentKnowledgeApi?: KnowledgeApi;
     readonly knowledgeApi?: KnowledgeApi;
     readonly hookApi?: HookApi;
     readonly mcpApi?: McpApi;