@pellux/goodvibes-agent 1.5.5 → 1.5.6

package/src/agent/session-registration.ts

@@ -0,0 +1,281 @@
+/**
+ * session-registration.ts
+ *
+ * Raw-REST mirror of the daemon's shared-session registration surface, written
+ * verbatim in the spirit of {@link ./operator-actions.ts}: request/response only,
+ * a Bearer token, an AbortController timeout, and the SAME classifyHttpFailure
+ * semantics (404 -> route unavailable, 401/403 -> auth required, network -> host
+ * unavailable). It deliberately imports NO SDK register/client types so the
+ * committed build compiles against the pinned npm @pellux/goodvibes-sdk (0.38.0),
+ * which does not ship POST /api/sessions/register at all. Against a 0.38.0 daemon
+ * this 404-degrades honestly; against a newer daemon (the sdk-dev overlay) it
+ * registers a real kind:'agent' record.
+ *
+ * Canonical vs transport axis (the S1 TRANSPORT ⊂ CANONICAL split): the record
+ * identity kind is ALWAYS 'agent' (see {@link SESSION_REGISTER_KIND}); the
+ * participant.surfaceKind carries the transport axis ('service' for this surface)
+ * and is NEVER set to 'agent'. `kind` is intentionally absent from the caller
+ * input so an unknown kind can never be emitted.
+ */
+
+export type JsonRecord = Record<string, unknown>;
+
+/** Only ever emitted value for the canonical record kind. */
+export const SESSION_REGISTER_KIND = 'agent' as const;
+export const SESSION_REGISTER_PATH = '/api/sessions/register';
+
+/** Default interactive-path wire timeout, mirrors external-runtime.ts fetchJson. */
+export const SESSION_REGISTER_TIMEOUT_MS = 1500;
+/** Best-effort close-on-shutdown budget; short so it never blocks teardown. */
+export const SESSION_CLOSE_TIMEOUT_MS = 500;
+
+export type SessionRegistrationFailureKind =
+  | 'auth_required'
+  | 'connected_host_unavailable'
+  | 'connected_host_route_unavailable'
+  | 'connected_host_error';
+
+export interface SessionRegistrationConnection {
+  readonly baseUrl: string;
+  readonly token: string | null;
+  readonly tokenPath?: string;
+}
+
+/** The participant triple carried onto the record; surfaceKind is the TRANSPORT axis. */
+export interface SessionRegistrationParticipant {
+  readonly surfaceKind: string;
+  readonly surfaceId: string;
+  readonly externalId?: string;
+  readonly userId?: string;
+  readonly displayName?: string;
+  readonly routeId?: string;
+  readonly lastSeenAt: number;
+}
+
+/**
+ * Caller input for a register/heartbeat upsert. NOTE: no `kind` field — the
+ * builder always stamps SESSION_REGISTER_KIND. Omitting `title` yields a
+ * heartbeat that never renames a titled session; omitting `reopen` keeps a
+ * closed session closed.
+ */
+export interface SessionRegistrationInput {
+  readonly sessionId: string;
+  readonly project?: string;
+  readonly title?: string;
+  readonly participant: SessionRegistrationParticipant;
+  readonly reopen?: boolean;
+}
+
+export interface SessionRegisterRequest {
+  readonly path: string;
+  readonly method: 'POST';
+  readonly body: JsonRecord;
+}
+
+export interface SessionMutationRequest {
+  readonly path: string;
+  readonly method: 'POST';
+}
+
+export interface SessionRecordSummary {
+  readonly id: string;
+  readonly kind: string;
+  readonly status: string;
+  readonly project?: string;
+  readonly title?: string;
+}
+
+/**
+ * Honest outcome discriminator. 'still_closed' is the Wave-1 heartbeat-resurrection
+ * guard: a 200 that carries conflict:{status:'closed'} with reopened:false MUST NOT
+ * be read as 'registered' or 'reopened'.
+ */
+export type SessionRegisterOutcome = 'registered' | 'reopened' | 'still_closed';
+
+export interface SessionRegisterSuccess {
+  readonly ok: true;
+  readonly outcome: SessionRegisterOutcome;
+  readonly reopened: boolean;
+  readonly conflict?: { readonly status: string };
+  readonly session?: SessionRecordSummary;
+}
+
+export interface SessionMutationFailure {
+  readonly ok: false;
+  readonly kind: SessionRegistrationFailureKind;
+  readonly status?: number;
+  readonly error: string;
+}
+
+export type SessionRegisterResult = SessionRegisterSuccess | SessionMutationFailure;
+export type SessionCloseResult = { readonly ok: true } | SessionMutationFailure;
+
+export function isRecord(value: unknown): value is JsonRecord {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+function summarizeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+async function readResponseBody(response: Response): Promise<unknown> {
+  const text = await response.text();
+  if (!text.trim()) return {};
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+/**
+ * Identical failure classification to operator-actions.ts:246-266 — 401/403 is
+ * auth, 404 is a missing route (the 0.38.0 / pre-spine daemon), anything else is
+ * a generic connected-host error.
+ */
+function classifyHttpFailure(status: number, body: unknown): SessionMutationFailure {
+  const detail = isRecord(body) && typeof body.error === 'string' ? body.error : '';
+  return {
+    ok: false,
+    status,
+    kind: status === 401 || status === 403
+      ? 'auth_required'
+      : status === 404
+        ? 'connected_host_route_unavailable'
+        : 'connected_host_error',
+    error: `HTTP ${status}${detail ? `: ${detail}` : ''}`,
+  };
+}
+
+export function buildSessionRegisterRequest(input: SessionRegistrationInput): SessionRegisterRequest {
+  const participant: JsonRecord = {
+    surfaceKind: input.participant.surfaceKind,
+    surfaceId: input.participant.surfaceId,
+    lastSeenAt: input.participant.lastSeenAt,
+  };
+  if (input.participant.externalId) participant.externalId = input.participant.externalId;
+  if (input.participant.userId) participant.userId = input.participant.userId;
+  if (input.participant.displayName) participant.displayName = input.participant.displayName;
+  if (input.participant.routeId) participant.routeId = input.participant.routeId;
+
+  const body: JsonRecord = {
+    sessionId: input.sessionId,
+    kind: SESSION_REGISTER_KIND,
+    participant,
+  };
+  if (input.project) body.project = input.project;
+  if (input.title) body.title = input.title;
+  // reopen is sent ONLY when explicitly true — the user resume verb. A heartbeat
+  // (reopen omitted) leaves a closed session closed.
+  if (input.reopen === true) body.reopen = true;
+
+  return { path: SESSION_REGISTER_PATH, method: 'POST', body };
+}
+
+export function buildSessionCloseRequest(sessionId: string): SessionMutationRequest {
+  return { path: `/api/sessions/${encodeURIComponent(sessionId)}/close`, method: 'POST' };
+}
+
+function summarizeSession(value: unknown): SessionRecordSummary | undefined {
+  if (!isRecord(value)) return undefined;
+  const id = typeof value.id === 'string' ? value.id : '';
+  if (!id) return undefined;
+  return {
+    id,
+    kind: typeof value.kind === 'string' ? value.kind : '',
+    status: typeof value.status === 'string' ? value.status : '',
+    ...(typeof value.project === 'string' ? { project: value.project } : {}),
+    ...(typeof value.title === 'string' ? { title: value.title } : {}),
+  };
+}
+
+function interpretRegisterResponse(body: unknown): SessionRegisterSuccess {
+  const record = isRecord(body) ? body : {};
+  const reopened = record.reopened === true;
+  const conflict = isRecord(record.conflict) && typeof record.conflict.status === 'string'
+    ? { status: record.conflict.status }
+    : undefined;
+  const session = summarizeSession(record.session);
+  const outcome: SessionRegisterOutcome = reopened
+    ? 'reopened'
+    : conflict?.status === 'closed'
+      ? 'still_closed'
+      : 'registered';
+  return {
+    ok: true,
+    outcome,
+    reopened,
+    ...(conflict ? { conflict } : {}),
+    ...(session ? { session } : {}),
+  };
+}
+
+export async function postSessionRegister(
+  connection: SessionRegistrationConnection,
+  input: SessionRegistrationInput,
+  options: { readonly timeoutMs?: number } = {},
+): Promise<SessionRegisterResult> {
+  if (!connection.token) {
+    return {
+      ok: false,
+      kind: 'auth_required',
+      error: connection.tokenPath
+        ? `no connected-host operator token found at ${connection.tokenPath}`
+        : 'no connected-host operator token found',
+    };
+  }
+  const request = buildSessionRegisterRequest(input);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? SESSION_REGISTER_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${connection.baseUrl}${request.path}`, {
+      method: request.method,
+      headers: {
+        authorization: `Bearer ${connection.token}`,
+        'content-type': 'application/json',
+      },
+      body: JSON.stringify(request.body),
+      signal: controller.signal,
+    });
+    const body = await readResponseBody(response);
+    if (!response.ok) return classifyHttpFailure(response.status, body);
+    return interpretRegisterResponse(body);
+  } catch (error) {
+    return { ok: false, kind: 'connected_host_unavailable', error: summarizeError(error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function postSessionClose(
+  connection: SessionRegistrationConnection,
+  sessionId: string,
+  options: { readonly timeoutMs?: number } = {},
+): Promise<SessionCloseResult> {
+  if (!connection.token) {
+    return {
+      ok: false,
+      kind: 'auth_required',
+      error: connection.tokenPath
+        ? `no connected-host operator token found at ${connection.tokenPath}`
+        : 'no connected-host operator token found',
+    };
+  }
+  const request = buildSessionCloseRequest(sessionId);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? SESSION_CLOSE_TIMEOUT_MS);
+  try {
+    const response = await fetch(`${connection.baseUrl}${request.path}`, {
+      method: request.method,
+      headers: { authorization: `Bearer ${connection.token}` },
+      signal: controller.signal,
+    });
+    const body = await readResponseBody(response);
+    if (!response.ok) return classifyHttpFailure(response.status, body);
+    return { ok: true };
+  } catch (error) {
+    return { ok: false, kind: 'connected_host_unavailable', error: summarizeError(error) };
+  } finally {
+    clearTimeout(timer);
+  }
+}

package/src/agent/vibe-file.ts

@@ -4,6 +4,12 @@ import type { ShellPathService } from '@/runtime/index.ts';
 import { GOODVIBES_AGENT_SURFACE_ROOT } from '../config/surface.ts';
 import { assertNoSecretLikeText } from './persona-registry.ts';
 import { parseMarkdownFrontmatter, stripMarkdownFrontmatter } from './markdown-frontmatter.ts';
+// W6-C2 (E6): VIBE.md is now a PROJECTION of persona/constraint records in the
+// canonical memory store, not a separate source of truth. renderVibeProjection emits
+// the same '## VIBE.md' block from those records (caveat preserved); the file is
+// demoted to an import/export FORMAT folded in via vibeBodyToConstraintOptions.
+import { renderVibeProjection, vibeBodyToConstraintOptions } from '@pellux/goodvibes-sdk/platform/state';
+import type { MemoryRegistry, MemoryScope } from '@pellux/goodvibes-sdk/platform/state';
 
 export type AgentVibeScope = 'project' | 'global';
 
@@ -205,6 +211,50 @@ export function buildVibePrompt(shellPaths: AgentVibePaths): string | null {
   return lines.join('\n');
 }
 
+/**
+ * W6-C2 (E6): the VIBE.md prompt block as a PROJECTION of persona/constraint records.
+ *
+ * This is the store-sourced replacement for buildVibePrompt (which reads the file
+ * directly). It renders the same '## GoodVibes Agent VIBE.md' block — including the
+ * precedence caveat — from the cls:'constraint' persona records in the canonical
+ * store, so persona instructions have a single source of truth alongside every other
+ * durable fact. Returns null when there are no persona records to project.
+ */
+export function buildVibeProjectionPrompt(memoryRegistry: MemoryRegistry): string | null {
+  return renderVibeProjection(memoryRegistry.getAll());
+}
+
+/**
+ * W6-C2 (E6): fold discovered VIBE.md files into the store as persona/constraint
+ * records — the file demoted to an IMPORT FORMAT. Each bullet becomes one record so a
+ * later single-record edit changes exactly one projected line. Secret-like content is
+ * already rejected by discoverVibeFiles (readVibeCandidate → assertNoSecretLikeText),
+ * so only clean bodies reach here. Idempotent enough for boot: importing the same body
+ * twice creates duplicate records only if their summaries differ, so callers should run
+ * this as a one-time migration, not every boot (mirrors the memory fold precedent).
+ */
+export async function importVibeFilesIntoMemory(
+  memoryRegistry: MemoryRegistry,
+  shellPaths: AgentVibePaths,
+): Promise<number> {
+  const snapshot = discoverVibeFiles(shellPaths);
+  let created = 0;
+  for (const file of snapshot.files) {
+    const scope: MemoryScope = file.scope === 'global' ? 'team' : 'project';
+    const name = file.frontmatter.name?.trim();
+    const options = vibeBodyToConstraintOptions(file.body, {
+      scope,
+      ...(name ? { name } : {}),
+      sourceRef: file.path,
+    });
+    for (const opts of options) {
+      await memoryRegistry.add(opts);
+      created += 1;
+    }
+  }
+  return created;
+}
+
 export function formatVibeStatus(snapshot: AgentVibeSnapshot): string {
   const lines: string[] = [
     'GoodVibes Agent VIBE.md',

package/src/cli/local-library-command-shared.ts

@@ -0,0 +1,146 @@
+import { createShellPathService } from '@/runtime/index.ts';
+import { AgentPersonaRegistry } from '../agent/persona-registry.ts';
+import { AgentSkillRegistry } from '../agent/skill-registry.ts';
+import type { CliCommandOutput } from './types.ts';
+import type { CliCommandRuntime } from './management.ts';
+
+/**
+ * Shared prelude for the Agent-local library CLI commands (personas, skills,
+ * skill bundles): option parsing, success/failure envelopes, and registry
+ * accessors. Split out of local-library-command.ts (W4-H1 ruling: the file
+ * cleanly contained three independent command handlers glued together) so
+ * personas-command.ts, skills-command.ts, and skill-bundle-command.ts can
+ * share one option-parsing/output prelude without duplicating it.
+ */
+
+export interface CommandSuccess<TData> {
+  readonly ok: true;
+  readonly kind: string;
+  readonly data: TData;
+}
+
+export interface CommandFailure {
+  readonly ok: false;
+  readonly kind: string;
+  readonly error: string;
+}
+
+export interface ParsedOptions {
+  readonly values: ReadonlyMap<string, string>;
+  readonly flags: ReadonlySet<string>;
+  readonly positionals: readonly string[];
+}
+
+export const LOCAL_LIBRARY_VALUE_OPTIONS = [
+  'name',
+  'description',
+  'body',
+  'procedure',
+  'tags',
+  'triggers',
+  'requires-env',
+  'requires-command',
+  'requires-commands',
+  'skills',
+  'provenance',
+] as const;
+
+export function jsonOrText(runtime: CliCommandRuntime, value: unknown, text: string): string {
+  return runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : text;
+}
+
+export function success<TData>(runtime: CliCommandRuntime, kind: string, data: TData, text: string): CliCommandOutput {
+  const value: CommandSuccess<TData> = { ok: true, kind, data };
+  return { output: jsonOrText(runtime, value, text), exitCode: 0 };
+}
+
+export function failure(runtime: CliCommandRuntime, kind: string, error: string, exitCode: number): CliCommandOutput {
+  const value: CommandFailure = { ok: false, kind, error };
+  return {
+    output: runtime.cli.flags.outputFormat === 'json' ? JSON.stringify(value, null, 2) : error,
+    exitCode,
+  };
+}
+
+export function parseOptions(args: readonly string[], valueOptions: readonly string[] = LOCAL_LIBRARY_VALUE_OPTIONS): ParsedOptions {
+  const valued = new Set(valueOptions);
+  const values = new Map<string, string>();
+  const flags = new Set<string>();
+  const positionals: string[] = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index] ?? '';
+    if (arg === '--') {
+      positionals.push(...args.slice(index + 1));
+      break;
+    }
+    if (!arg.startsWith('--')) {
+      positionals.push(arg);
+      continue;
+    }
+    const raw = arg.slice(2);
+    const equalIndex = raw.indexOf('=');
+    if (equalIndex >= 0) {
+      values.set(raw.slice(0, equalIndex), raw.slice(equalIndex + 1));
+      continue;
+    }
+    const name = raw;
+    const next = args[index + 1];
+    if (next !== undefined && (valued.has(name) || !next.startsWith('--'))) {
+      values.set(name, next);
+      index += 1;
+      continue;
+    }
+    flags.add(name);
+  }
+  return { values, flags, positionals };
+}
+
+export function optionValue(options: ParsedOptions, name: string): string | undefined {
+  const value = options.values.get(name);
+  if (value === undefined) return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+export function requiredOption(options: ParsedOptions, name: string, usage: string): string {
+  const value = optionValue(options, name);
+  if (!value) throw new Error(`${usage}\nMissing --${name}.`);
+  return value;
+}
+
+export function csvOption(options: ParsedOptions, name: string): readonly string[] | undefined {
+  const value = optionValue(options, name);
+  if (value === undefined) return undefined;
+  return value.split(',').map((entry) => entry.trim()).filter(Boolean);
+}
+
+export function hasFlag(options: ParsedOptions, name: string): boolean {
+  return options.flags.has(name);
+}
+
+export function personaRegistry(runtime: CliCommandRuntime): AgentPersonaRegistry {
+  return AgentPersonaRegistry.fromShellPaths(createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  }));
+}
+
+export function skillRegistry(runtime: CliCommandRuntime): AgentSkillRegistry {
+  return AgentSkillRegistry.fromShellPaths(createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  }));
+}
+
+export function shellPaths(runtime: CliCommandRuntime): ReturnType<typeof createShellPathService> {
+  return createShellPathService({
+    workingDirectory: runtime.workingDirectory,
+    homeDirectory: runtime.homeDirectory,
+  });
+}
+
+export function errorOutput(runtime: CliCommandRuntime, error: unknown, kind: string): CliCommandOutput {
+  const message = error instanceof Error ? error.message : String(error);
+  const exitCode = message.startsWith('Usage:') || message.includes('\nMissing --') ? 2 : 1;
+  return failure(runtime, kind, message, exitCode);
+}

package/src/cli/management.ts

@@ -29,7 +29,8 @@ import { classifyProviderSetup } from './provider-classification.ts';
 import { handleBundleCommand } from './bundle-command.ts';
 import { handleSecrets, handleSessions, handleTasks, renderPairing, renderSubscriptions } from './management-commands.ts';
 import { handleAgentKnowledgeCommand, handleAgentKnowledgeShortcutCommand, handleCompatCommand, handleDelegateCommand } from './agent-knowledge-command.ts';
-import { handlePersonasCommand, handleSkillsCommand } from './local-library-command.ts';
+import { handlePersonasCommand } from './personas-command.ts';
+import { handleSkillsCommand } from './skills-command.ts';
 import { handleMemoryCommand } from './memory-command.ts';
 import { handleProfilesCommand } from './profiles-command.ts';
 import { handleRoutinesCommand } from './routines-command.ts';