@pellux/goodvibes-agent 1.1.7 → 1.2.0

package/src/tools/agent-model-compare-types.ts

@@ -0,0 +1,191 @@
+import type { ArtifactStore } from '@pellux/goodvibes-sdk/platform/artifacts';
+import type { ChatResponse, LLMProvider } from '@pellux/goodvibes-sdk/platform/providers';
+
+export interface AgentModelCompareToolArgs {
+  readonly mode?: unknown;
+  readonly prompt?: unknown;
+  readonly modelRefs?: unknown;
+  readonly candidateCount?: unknown;
+  readonly rubric?: unknown;
+  readonly systemPrompt?: unknown;
+  readonly maxTokens?: unknown;
+  readonly reveal?: unknown;
+  readonly saveArtifact?: unknown;
+  readonly benchmarkKind?: unknown;
+  readonly comparisonId?: unknown;
+  readonly artifactId?: unknown;
+  readonly leftArtifactId?: unknown;
+  readonly rightArtifactId?: unknown;
+  readonly sectionId?: unknown;
+  readonly winner?: unknown;
+  readonly winnerBlindId?: unknown;
+  readonly reasons?: unknown;
+  readonly notes?: unknown;
+  readonly decision?: unknown;
+  readonly limit?: unknown;
+  readonly includeReasons?: unknown;
+  readonly taskType?: unknown;
+  readonly documentId?: unknown;
+  readonly relatedArtifactIds?: unknown;
+  readonly previewBytes?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+export interface AgentModelCompareRouteUpdateResult {
+  readonly previousModel?: string;
+  readonly selectedModel: string;
+}
+
+export interface AgentModelCompareCatalogModel {
+  readonly id?: string;
+  readonly modelId?: string;
+  readonly provider?: string;
+  readonly providerId?: string;
+  readonly registryKey?: string;
+  readonly displayName?: string;
+  readonly selectable?: boolean;
+  readonly current?: boolean;
+  readonly contextWindow?: number;
+}
+
+export interface AgentModelCompareModelCatalog {
+  readonly listModels: (query?: { readonly selectableOnly?: boolean }) => readonly AgentModelCompareCatalogModel[] | Promise<readonly AgentModelCompareCatalogModel[]>;
+  readonly getCurrentModel?: () => AgentModelCompareCatalogModel | Promise<AgentModelCompareCatalogModel>;
+  readonly recordModelUsage?: (registryKey: string) => Promise<unknown>;
+}
+
+export interface AgentModelCompareProviderRegistry {
+  readonly getForModel: (modelId: string, provider?: string) => LLMProvider;
+}
+
+export type AgentModelCompareArtifactStore = Pick<ArtifactStore, 'create'> & Partial<Pick<ArtifactStore, 'list' | 'readContent'>>;
+
+export interface AgentModelCompareToolDeps {
+  readonly modelCatalog: AgentModelCompareModelCatalog;
+  readonly providerRegistry: AgentModelCompareProviderRegistry;
+  readonly artifactStore?: AgentModelCompareArtifactStore;
+  readonly applyModelRoute?: (registryKey: string) => AgentModelCompareRouteUpdateResult | Promise<AgentModelCompareRouteUpdateResult>;
+}
+
+export interface ResolvedCompareModel {
+  readonly registryKey: string;
+  readonly modelId: string;
+  readonly providerId: string;
+  readonly displayName: string;
+  readonly current: boolean;
+}
+
+export type CompareCandidateStatus = 'completed' | 'failed';
+
+export interface CompareCandidateResult {
+  readonly blindId: string;
+  readonly model: ResolvedCompareModel;
+  readonly status: CompareCandidateStatus;
+  readonly content: string;
+  readonly stopReason?: string;
+  readonly usage?: ChatResponse['usage'];
+  readonly latencyMs: number;
+  readonly toolCallCount?: number;
+  readonly error?: string;
+}
+
+export interface StoredComparison {
+  readonly comparisonId: string;
+  readonly createdAt: string;
+  readonly promptPreview: string;
+  readonly rubric: string;
+  readonly sourceArtifact?: SavedComparisonArtifact;
+  readonly benchmarkKind?: string;
+  readonly taskType?: string;
+  readonly documentId?: string;
+  readonly candidates: readonly CompareCandidateResult[];
+  readonly artifact?: SavedComparisonArtifact;
+  readonly artifactStatus?: ComparisonArtifactStatus;
+}
+
+export interface LoadedComparisonJudgment {
+  readonly artifact: SavedComparisonArtifact;
+  readonly judgmentId: string;
+  readonly comparisonId: string;
+  readonly winnerBlindId: string;
+  readonly reasons: string;
+  readonly notes: string;
+  readonly revealIncludedInJudgment: boolean;
+  readonly sourceArtifactId?: string;
+  readonly benchmarkKind?: string;
+  readonly taskType?: string;
+  readonly documentId?: string;
+  readonly winnerModel?: {
+    readonly registryKey: string;
+    readonly providerId: string;
+    readonly modelId: string;
+    readonly displayName: string;
+  };
+}
+
+export interface LoadedComparisonHandoff {
+  readonly artifact: SavedComparisonArtifact;
+  readonly handoffId: string;
+  readonly sourceArtifactId: string;
+  readonly sourceKind: 'comparison' | 'judgment';
+  readonly comparisonId: string;
+  readonly relatedArtifactIds: readonly string[];
+  readonly revealIncludedInHandoff: boolean;
+}
+
+export interface SavedComparisonArtifact {
+  readonly artifactId: string;
+  readonly filename?: string;
+  readonly mimeType: string;
+  readonly sizeBytes: number;
+  readonly documentId?: string;
+}
+
+export interface ComparisonArtifactStatus {
+  readonly state: 'saved' | 'disabled' | 'unavailable' | 'failed';
+  readonly message: string;
+}
+
+export const MODE_RUN = 'run';
+export const MODE_REVEAL = 'reveal';
+export const MODE_REVIEW = 'review';
+export const MODE_SIDE_BY_SIDE = 'sideBySide';
+export const MODE_JUDGE = 'judge';
+export const MODE_APPLY = 'apply';
+export const MODE_ROUTE_DECISION = 'routeDecision';
+export const MODE_EXPORT = 'export';
+export const MODE_HANDOFF = 'handoff';
+export const MODE_HANDOFF_ARCHIVE = 'handoffArchive';
+export const MODE_HANDOFF_DIFF = 'handoffDiff';
+export const MODE_ANALYTICS = 'analytics';
+export const MODE_SYNTHESIS = 'synthesis';
+export const MAX_PROMPT_CHARS = 24_000;
+export const MIN_CANDIDATES = 2;
+export const MAX_CANDIDATES = 4;
+export const DEFAULT_CANDIDATE_COUNT = 2;
+export const DEFAULT_MAX_TOKENS = 2_048;
+export const MAX_COMPLETION_TOKENS = 8_192;
+export const DEFAULT_CANDIDATE_OUTPUT_CHARS = 12_000;
+export const MAX_SOURCE_ARTIFACT_BYTES = 18_000;
+export const MAX_HANDOFF_ARTIFACT_BYTES = 40_000;
+export const MAX_HANDOFF_ARCHIVE_ARTIFACTS = 100;
+export const MAX_HANDOFF_DIFF_INPUT_LINES = 360;
+export const MAX_HANDOFF_DIFF_ROWS = 120;
+export const MAX_HANDOFF_DIFF_SECTION_PREVIEW_CHARS = 180;
+export const DEFAULT_SIDE_BY_SIDE_PREVIEW_BYTES = 2_000;
+export const MAX_SIDE_BY_SIDE_PREVIEW_BYTES = 10_000;
+export const COMPARISON_STORE_LIMIT = 25;
+export const BLIND_LABELS = ['A', 'B', 'C', 'D'] as const;
+
+export const SYNTHESIS_THEMES: readonly {
+  readonly label: string;
+  readonly pattern: RegExp;
+}[] = [
+  { label: 'Concrete/actionable output', pattern: /\b(concrete|actionable|specific|steps?|route|command|practical)\b/i },
+  { label: 'Clear/scannable communication', pattern: /\b(clear|clarity|concise|scan|scannable|readable|structured|tone)\b/i },
+  { label: 'Accuracy and faithfulness', pattern: /\b(accurate|accuracy|faithful|correct|factual|hallucinat|source|evidence)\b/i },
+  { label: 'Context fit', pattern: /\b(context|project|user|goal|fit|rubric|instruction)\b/i },
+  { label: 'Safety and risk handling', pattern: /\b(safe|safety|risk|guard|permission|confirm|policy)\b/i },
+  { label: 'Speed and efficiency', pattern: /\b(fast|speed|latency|efficient|short|token)\b/i },
+];

package/src/tools/agent-model-compare-utils.ts

@@ -0,0 +1,93 @@
+export function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+export function readRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    ? value as Record<string, unknown>
+    : null;
+}
+
+export function readBoolean(value: unknown): boolean {
+  return value === true || value === 'true' || value === 'yes';
+}
+
+export function readOptionalBoolean(value: unknown, fallback: boolean): boolean {
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'string' && value.trim() === '') return fallback;
+  return readBoolean(value);
+}
+
+export function readNumber(value: unknown, fallback: number): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return fallback;
+  return Math.trunc(parsed);
+}
+
+export function readBenchmarkKind(value: unknown): string {
+  return readComparisonTag(value);
+}
+
+export function readComparisonTag(value: unknown): string {
+  return readString(value)
+    .replace(/[\r\n\t]+/g, ' ')
+    .replace(/\s+/g, ' ')
+    .slice(0, 120)
+    .trim();
+}
+
+export function clamp(value: number, min: number, max: number): number {
+  return Math.max(min, Math.min(max, value));
+}
+
+export function failure(error: string): { readonly success: false; readonly error: string } {
+  return { success: false, error };
+}
+
+export function output(text: string): { readonly success: true; readonly output: string } {
+  return { success: true, output: text };
+}
+
+export function previewText(value: string, limit = 96): string {
+  const normalized = value.replace(/\s+/g, ' ').trim();
+  if (normalized.length <= limit) return normalized;
+  return `${normalized.slice(0, limit - 3).trimEnd()}...`;
+}
+
+export function isTextLike(mimeType: string): boolean {
+  const normalized = mimeType.toLowerCase();
+  return normalized.startsWith('text/')
+    || normalized.includes('json')
+    || normalized.includes('xml')
+    || normalized.includes('yaml')
+    || normalized.includes('csv')
+    || normalized.includes('javascript')
+    || normalized.includes('typescript')
+    || normalized.includes('markdown');
+}
+
+export function readModelRefs(value: unknown): readonly string[] {
+  if (Array.isArray(value)) {
+    return value
+      .map((entry) => readString(entry))
+      .filter(Boolean);
+  }
+  const text = readString(value);
+  if (!text) return [];
+  return text.split(/[\n,]/).map((entry) => entry.trim()).filter(Boolean);
+}
+
+export function readStringList(value: unknown): readonly string[] {
+  const raw = Array.isArray(value)
+    ? value
+    : readString(value).split(/[\n,]/);
+  const seen = new Set<string>();
+  const result: string[] = [];
+  for (const entry of raw) {
+    const text = readString(entry);
+    if (!text || seen.has(text)) continue;
+    seen.add(text);
+    result.push(text);
+  }
+  return result;
+}

package/src/tools/agent-models-tool.ts

@@ -0,0 +1,208 @@
+import type { Tool } from '@pellux/goodvibes-sdk/platform/types';
+import type { ToolRegistry } from '@pellux/goodvibes-sdk/platform/tools';
+import type { CommandContext, CommandRegistry } from '../input/command-registry.ts';
+import { createAgentHarnessTool } from './agent-harness-tool.ts';
+
+type AgentModelsAction =
+  | 'status'
+  | 'route'
+  | 'local'
+  | 'providers'
+  | 'provider'
+  | 'smoke';
+
+interface AgentModelsToolArgs {
+  readonly action?: unknown;
+  readonly mode?: unknown;
+  readonly id?: unknown;
+  readonly modelRouteId?: unknown;
+  readonly routeId?: unknown;
+  readonly providerId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+  readonly timeoutMs?: unknown;
+  readonly confirm?: unknown;
+  readonly explicitUserRequest?: unknown;
+}
+
+interface AgentModelsToolDeps {
+  readonly commandRegistry: CommandRegistry;
+  readonly commandContext: CommandContext;
+  readonly toolRegistry: ToolRegistry;
+  readonly harnessTool?: Tool;
+}
+
+function error(message: string): { readonly success: false; readonly error: string } {
+  return { success: false, error: message };
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function normalizeModelsAction(value: unknown): AgentModelsAction | null {
+  const action = readString(value).toLowerCase().replace(/-/g, '_');
+  if (!action) return null;
+  if (action === 'status' || action === 'routing' || action === 'routes' || action === 'models' || action === 'model' || action === 'readiness' || action === 'route_readiness') return 'status';
+  if (action === 'route' || action === 'model_route' || action === 'inspect' || action === 'show' || action === 'candidate' || action === 'endpoint') return 'route';
+  if (action === 'local' || action === 'cookbook' || action === 'local_cookbook' || action === 'recipes' || action === 'recipe' || action === 'ollama' || action === 'llama_cpp' || action === 'llamacpp' || action === 'vllm' || action === 'local_servers') return 'local';
+  if (action === 'providers' || action === 'provider_accounts' || action === 'accounts' || action === 'subscriptions' || action === 'auth' || action === 'logins') return 'providers';
+  if (action === 'provider' || action === 'provider_account' || action === 'account' || action === 'subscription' || action === 'auth_status') return 'provider';
+  if (action === 'smoke' || action === 'local_smoke' || action === 'check_local' || action === 'check_servers' || action === 'server_health' || action === 'local_server_health' || action === 'run_local_model_smoke') return 'smoke';
+  return null;
+}
+
+function readAction(args: AgentModelsToolArgs): AgentModelsAction {
+  const explicit = normalizeModelsAction(args.action) ?? normalizeModelsAction(args.mode);
+  if (explicit) return explicit;
+  if (readString(args.providerId)) return 'provider';
+  if (readString(args.modelRouteId) || readString(args.routeId)) return 'route';
+  return 'status';
+}
+
+function compactArgs(entries: Record<string, unknown>): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(entries).filter(([, value]) => value !== undefined && value !== ''));
+}
+
+function routeLookup(args: AgentModelsToolArgs): string {
+  return readString(args.modelRouteId)
+    || readString(args.routeId)
+    || readString(args.id);
+}
+
+function providerLookup(args: AgentModelsToolArgs): string {
+  return readString(args.providerId)
+    || readString(args.id);
+}
+
+function confirmedArgs(args: AgentModelsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    confirm: args.confirm,
+    explicitUserRequest: args.explicitUserRequest,
+  });
+}
+
+function statusArgs(args: AgentModelsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'model_routing',
+    query: args.query ?? args.target,
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function routeArgs(args: AgentModelsToolArgs): Record<string, unknown> {
+  const modelRouteId = routeLookup(args);
+  return compactArgs({
+    mode: 'model_route',
+    modelRouteId,
+    target: modelRouteId ? undefined : args.target,
+    query: modelRouteId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function localArgs(args: AgentModelsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'model_routing',
+    query: args.query ?? args.target ?? 'local',
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function providersArgs(args: AgentModelsToolArgs): Record<string, unknown> {
+  return compactArgs({
+    mode: 'provider_accounts',
+    query: args.query ?? args.target,
+    includeParameters: args.includeParameters,
+    limit: args.limit,
+  });
+}
+
+function providerArgs(args: AgentModelsToolArgs): Record<string, unknown> {
+  const providerId = providerLookup(args);
+  return compactArgs({
+    mode: 'provider_account',
+    providerId,
+    target: providerId ? undefined : args.target,
+    query: providerId ? undefined : args.query,
+    includeParameters: args.includeParameters,
+  });
+}
+
+function smokeArgs(args: AgentModelsToolArgs): Record<string, unknown> {
+  const modelRouteId = routeLookup(args);
+  return compactArgs({
+    mode: 'run_local_model_smoke',
+    modelRouteId,
+    target: modelRouteId ? undefined : args.target,
+    query: modelRouteId ? undefined : args.query,
+    limit: args.limit,
+    timeoutMs: args.timeoutMs,
+    ...confirmedArgs(args),
+  });
+}
+
+export function createAgentModelsTool(deps: AgentModelsToolDeps): Tool {
+  const harnessTool = deps.harnessTool ?? createAgentHarnessTool({
+    commandRegistry: deps.commandRegistry,
+    commandContext: deps.commandContext,
+    toolRegistry: deps.toolRegistry,
+  });
+
+  return {
+    definition: {
+      name: 'models',
+      description: 'Inspect model routes, providers, cookbook, and checks.',
+      parameters: {
+        type: 'object',
+        properties: {
+          action: {
+            type: 'string',
+            enum: ['status', 'route', 'local', 'providers', 'provider', 'smoke'],
+            description: 'Read model/provider posture; confirm local server smoke checks.',
+          },
+          mode: { type: 'string', description: 'Alias for action.' },
+          id: { type: 'string', description: 'Model route or provider id alias.' },
+          modelRouteId: { type: 'string', description: 'Model route, local endpoint, or cookbook route id.' },
+          routeId: { type: 'string', description: 'Model route id alias.' },
+          providerId: { type: 'string', description: 'Provider account id.' },
+          target: { type: 'string', description: 'Lookup target.' },
+          query: { type: 'string', description: 'Search text.' },
+          includeParameters: { type: 'boolean', description: 'Include detailed route contracts.' },
+          limit: { type: 'number', description: 'Maximum rows.' },
+          timeoutMs: { type: 'number', description: 'Optional timeout for local model smoke checks.' },
+          confirm: { type: 'boolean', description: 'Required true for local server smoke checks.' },
+          explicitUserRequest: { type: 'string', description: 'User request authorizing confirmed local server checks.' },
+        },
+        additionalProperties: false,
+      },
+      sideEffects: ['state'],
+      concurrency: 'serial',
+    },
+    execute: async (rawArgs: unknown) => {
+      const args = (rawArgs && typeof rawArgs === 'object' && !Array.isArray(rawArgs) ? rawArgs : {}) as AgentModelsToolArgs;
+      const action = readAction(args);
+
+      if (action === 'status') return harnessTool.execute(statusArgs(args));
+      if (action === 'route') return harnessTool.execute(routeArgs(args));
+      if (action === 'local') return harnessTool.execute(localArgs(args));
+      if (action === 'providers') return harnessTool.execute(providersArgs(args));
+      if (action === 'provider') return harnessTool.execute(providerArgs(args));
+      if (action === 'smoke') return harnessTool.execute(smokeArgs(args));
+
+      return error('Unknown models action. Use action:"status" for model routing readiness.');
+    },
+  };
+}
+
+export function registerAgentModelsTool(
+  registry: ToolRegistry,
+  commandRegistry: CommandRegistry,
+  commandContext: CommandContext,
+): void {
+  if (!registry.has('models')) registry.register(createAgentModelsTool({ commandRegistry, commandContext, toolRegistry: registry }));
+}

package/src/tools/agent-operator-action-tool.ts

@@ -62,7 +62,7 @@ export function createAgentOperatorActionTool(
           },
           scheduleId: {
             type: 'string',
-            description: 'Schedule id for schedules.run.',
+            description: 'Schedule id for run, enable, disable, or delete.',
           },
           note: {
             type: 'string',