@pellux/goodvibes-agent 1.0.30 → 1.0.33

package/src/tools/agent-harness-setup-posture.ts

@@ -0,0 +1,295 @@
+import type { OnboardingStep1CapabilityItem, OnboardingSurfaceRecord } from '../runtime/onboarding/index.ts';
+import { collectOnboardingSnapshot, deriveStep1Capabilities, deriveStep1CapabilityFlags } from '../runtime/onboarding/index.ts';
+import type { CommandContext } from '../input/command-registry.ts';
+import { buildProviderAccountSnapshot } from '../panels/provider-account-snapshot.ts';
+import { requireLocalUserAuthManager, requirePlatform, requireProvider, requireSecretsManager, requireServiceRegistry, requireShellPaths, requireSubscriptionManager } from '../input/commands/runtime-services.ts';
+
+export interface AgentHarnessSetupArgs {
+  readonly setupItemId?: unknown;
+  readonly target?: unknown;
+  readonly query?: unknown;
+  readonly includeParameters?: unknown;
+  readonly limit?: unknown;
+}
+
+type SetupResolution =
+  | { readonly status: 'found'; readonly item: Record<string, unknown> }
+  | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
+  | { readonly status: 'missing_lookup'; readonly usage: string };
+
+type SetupLookupSource = 'setupItemId' | 'target' | 'query';
+
+interface SurfaceRegistryLike {
+  syncConfiguredSurfaces(): readonly OnboardingSurfaceRecord[];
+}
+
+function readString(value: unknown): string {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function readLimit(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.max(1, Math.min(500, Math.trunc(parsed)));
+}
+
+function safeIso(value: number | null | undefined): string | null {
+  if (typeof value !== 'number' || !Number.isFinite(value)) return null;
+  return new Date(value).toISOString();
+}
+
+function surfaceRegistry(context: CommandContext): SurfaceRegistryLike | undefined {
+  const candidate = (context.platform as { readonly surfaceRegistry?: unknown }).surfaceRegistry;
+  if (candidate && typeof candidate === 'object' && 'syncConfiguredSurfaces' in candidate) {
+    return candidate as SurfaceRegistryLike;
+  }
+  return undefined;
+}
+
+async function collectSnapshot(context: CommandContext) {
+  const registry = surfaceRegistry(context);
+  return await collectOnboardingSnapshot({
+    config: requirePlatform(context).configManager,
+    shellPaths: requireShellPaths(context),
+    acknowledgementScope: 'project',
+    subscriptions: requireSubscriptionManager(context),
+    secrets: requireSecretsManager(context),
+    auth: requireLocalUserAuthManager(context),
+    services: requireServiceRegistry(context),
+    ...(registry ? {
+      surfaces: {
+        list: () => registry.syncConfiguredSurfaces(),
+      },
+    } : {}),
+    providerAccounts: {
+      loadSnapshot: () => buildProviderAccountSnapshot({
+        providerModels: requireProvider(context).providerRegistry,
+        services: requireServiceRegistry(context),
+        subscriptions: requireSubscriptionManager(context),
+        environment: {
+          hasEnvironmentVariable: (name: string) => Boolean(process.env[name]),
+        },
+      }),
+    },
+  });
+}
+
+function lookupFromArgs(args: AgentHarnessSetupArgs): { readonly source: SetupLookupSource; readonly input: string } | null {
+  const setupItemId = readString(args.setupItemId);
+  if (setupItemId) return { source: 'setupItemId', input: setupItemId };
+  const target = readString(args.target);
+  if (target) return { source: 'target', input: target };
+  const query = readString(args.query);
+  return query ? { source: 'query', input: query } : null;
+}
+
+function itemSearchText(item: OnboardingStep1CapabilityItem): string {
+  return [
+    item.id,
+    item.label,
+    item.detail,
+    item.selected ? 'selected ready configured enabled' : 'optional attention unselected',
+  ].join('\n').toLowerCase();
+}
+
+function summarizeLocalBehavior(snapshot: Awaited<ReturnType<typeof collectSnapshot>>): Record<string, unknown> {
+  const discovery = snapshot.localBehaviorDiscovery;
+  return {
+    personas: discovery.personas,
+    skills: discovery.skills,
+    routines: discovery.routines,
+  };
+}
+
+function signalsForItem(
+  item: OnboardingStep1CapabilityItem,
+  snapshot: Awaited<ReturnType<typeof collectSnapshot>>,
+): Record<string, unknown> {
+  if (item.id === 'provider-access') {
+    return {
+      currentRoute: snapshot.providerRouting,
+      providerAccounts: {
+        providers: snapshot.providerAccounts?.providers.length ?? 0,
+        configured: snapshot.providerAccounts?.configuredCount ?? 0,
+        issues: snapshot.providerAccounts?.issueCount ?? 0,
+      },
+      subscriptions: {
+        active: snapshot.subscriptions.active.length,
+        pending: snapshot.subscriptions.pending.length,
+        activeProviderIds: snapshot.subscriptions.activeProviderIds,
+        pendingProviderIds: snapshot.subscriptions.pendingProviderIds,
+      },
+      credentialReferences: snapshot.secrets.records.length,
+    };
+  }
+  if (item.id === 'local-behavior') {
+    return summarizeLocalBehavior(snapshot);
+  }
+  if (item.id === 'communication-channels') {
+    return {
+      configuredEnabledKinds: snapshot.surfaces.configuredEnabledKinds,
+      surfaces: snapshot.surfaces.records.map((surface) => ({
+        id: surface.id,
+        kind: surface.kind,
+        label: surface.label,
+        enabled: surface.enabled,
+        state: surface.state,
+        capabilities: surface.capabilities,
+      })),
+    };
+  }
+  if (item.id === 'automation-review') {
+    return {
+      permissionsMode: snapshot.runtimeDefaults.permissionsMode,
+      helperEnabled: snapshot.providerRouting.helperEnabled,
+      toolLlmEnabled: snapshot.providerRouting.toolLlmEnabled,
+    };
+  }
+  if (item.id === 'operator-terminal') {
+    return {
+      display: snapshot.runtimeDefaults.display,
+      setupMarker: {
+        scope: snapshot.acknowledgements.scope,
+        exists: snapshot.acknowledgements.exists,
+        updatedAt: safeIso(snapshot.acknowledgements.updatedAt),
+        source: snapshot.acknowledgements.source,
+        mode: snapshot.acknowledgements.mode ?? null,
+      },
+      collectionIssues: snapshot.collectionIssues,
+    };
+  }
+  return {
+    status: item.selected ? 'covered' : 'available',
+  };
+}
+
+function describeItem(
+  item: OnboardingStep1CapabilityItem,
+  snapshot: Awaited<ReturnType<typeof collectSnapshot>>,
+  options: {
+    readonly includeParameters?: boolean;
+    readonly lookup?: Record<string, unknown>;
+  } = {},
+): Record<string, unknown> {
+  return {
+    setupItemId: item.id,
+    label: item.label,
+    selected: item.selected,
+    detail: item.detail,
+    signals: signalsForItem(item, snapshot),
+    ...(options.lookup ? { lookup: options.lookup } : {}),
+    policy: {
+      effect: 'read-only',
+      values: 'Setup posture returns onboarding readiness, counts, safe setting keys, and route metadata only; secret values and raw provider tokens are never returned.',
+      mutation: 'Setup apply, provider auth, local behavior import/create, channel delivery, and starter profile changes stay visible workspace, settings, slash-command, or first-class tool flows.',
+    },
+    ...(options.includeParameters ? {
+      modelAccess: {
+        inspectSetup: 'agent_harness mode:"setup_posture"',
+        inspectSetupItem: 'agent_harness mode:"setup_item"',
+        openOnboarding: 'agent_harness mode:"open_ui_surface" surfaceId:"onboarding" confirm:true',
+        setupWorkspace: 'agent_harness mode:"workspace_action" target:"setup"',
+        settings: 'agent_harness modes settings/get_setting/set_setting/reset_setting',
+        providerRouting: 'agent_harness mode:"model_routing"',
+        providerAccounts: 'agent_harness mode:"provider_accounts"',
+        channels: 'agent_harness mode:"channels"',
+        media: 'agent_harness mode:"media_posture"',
+        security: 'agent_harness mode:"security_posture"',
+      },
+    } : {}),
+  };
+}
+
+function describeCandidate(item: OnboardingStep1CapabilityItem): Record<string, unknown> {
+  return {
+    setupItemId: item.id,
+    label: item.label,
+    selected: item.selected,
+  };
+}
+
+export async function setupPostureCatalogStatus(context: CommandContext): Promise<Record<string, unknown>> {
+  const snapshot = await collectSnapshot(context);
+  return {
+    modes: ['setup_posture', 'setup_item'],
+    capabilities: deriveStep1Capabilities(snapshot).length,
+    collectionIssues: snapshot.collectionIssues.length,
+    setupMarkerExists: snapshot.acknowledgements.exists,
+    readOnly: true,
+  };
+}
+
+export async function setupPostureSummary(context: CommandContext, args: AgentHarnessSetupArgs): Promise<Record<string, unknown>> {
+  const snapshot = await collectSnapshot(context);
+  const query = readString(args.query).toLowerCase();
+  const includeParameters = args.includeParameters === true;
+  const all = deriveStep1Capabilities(snapshot);
+  const filtered = all
+    .filter((item) => !query || itemSearchText(item).includes(query))
+    .slice(0, readLimit(args.limit, 100));
+  return {
+    capturedAt: new Date(snapshot.capturedAt).toISOString(),
+    setupMarker: {
+      scope: snapshot.acknowledgements.scope,
+      exists: snapshot.acknowledgements.exists,
+      updatedAt: safeIso(snapshot.acknowledgements.updatedAt),
+      source: snapshot.acknowledgements.source,
+      mode: snapshot.acknowledgements.mode ?? null,
+      acceptedCount: Object.values(snapshot.acknowledgements.accepted).filter(Boolean).length,
+    },
+    summary: {
+      capabilities: all.length,
+      selectedCapabilities: all.filter((item) => item.selected).length,
+      collectionIssues: snapshot.collectionIssues.length,
+      services: snapshot.services.total,
+      oauthProviders: snapshot.services.oauthProviderIds.length,
+      subscriptionSessions: snapshot.subscriptions.active.length,
+      pendingSubscriptionSessions: snapshot.subscriptions.pending.length,
+      providerAccounts: snapshot.providerAccounts?.providers.length ?? 0,
+      providerAccountIssues: snapshot.providerAccounts?.issueCount ?? 0,
+      secretsStoredKeys: snapshot.secrets.review.storedKeys,
+      secretRecordCount: snapshot.secrets.records.length,
+      authUsers: snapshot.auth.snapshot.userCount,
+      authSessions: snapshot.auth.snapshot.sessionCount,
+      enabledSurfaceKinds: snapshot.surfaces.configuredEnabledKinds.length,
+      localBehavior: summarizeLocalBehavior(snapshot),
+      capabilityFlags: deriveStep1CapabilityFlags(snapshot),
+    },
+    currentRoute: snapshot.providerRouting,
+    issues: snapshot.collectionIssues,
+    capabilities: filtered.map((item) => describeItem(item, snapshot, { includeParameters })),
+    returned: filtered.length,
+    total: all.length,
+    policy: 'Read-only setup/onboarding posture. Apply, import, auth, profile, channel, and setting mutations remain confirmation-gated through visible workspace, settings, slash-command, or first-class tool flows.',
+  };
+}
+
+export async function describeHarnessSetupItem(context: CommandContext, args: AgentHarnessSetupArgs): Promise<SetupResolution> {
+  const lookup = lookupFromArgs(args);
+  if (!lookup) {
+    return {
+      status: 'missing_lookup',
+      usage: 'setup_item requires setupItemId, target, or query. Use mode:"setup_posture" to inspect setup item ids.',
+    };
+  }
+  const snapshot = await collectSnapshot(context);
+  const items = deriveStep1Capabilities(snapshot);
+  const normalized = lookup.input.toLowerCase();
+  const exact = items.find((item) => item.id === lookup.input);
+  if (exact) return { status: 'found', item: describeItem(exact, snapshot, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'id' } }) };
+  const insensitive = items.find((item) => item.id.toLowerCase() === normalized);
+  if (insensitive) return { status: 'found', item: describeItem(insensitive, snapshot, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'case-insensitive-id' } }) };
+  const searched = items.filter((item) => itemSearchText(item).includes(normalized));
+  if (searched.length === 1) return { status: 'found', item: describeItem(searched[0]!, snapshot, { includeParameters: true, lookup: { ...lookup, resolvedBy: 'search' } }) };
+  if (searched.length > 1) {
+    return {
+      status: 'ambiguous',
+      input: lookup.input,
+      candidates: searched.slice(0, 8).map(describeCandidate),
+    };
+  }
+  return {
+    status: 'missing_lookup',
+    usage: `Unknown setup item ${lookup.input}. Use mode:"setup_posture" to inspect setup item ids.`,
+  };
+}

package/src/tools/agent-harness-tool-schema.ts

@@ -2,10 +2,22 @@ export const AGENT_HARNESS_MODES = [
   'summary', 'cli_commands', 'cli_command', 'panels', 'panel', 'open_panel',
   'ui_surfaces', 'ui_surface', 'open_ui_surface',
   'shortcuts', 'keybindings', 'keybinding', 'run_keybinding', 'set_keybinding', 'reset_keybinding',
-  'commands', 'command', 'run_command', 'settings', 'get_setting', 'set_setting',
+  'commands', 'command', 'run_command', 'channels', 'channel', 'notifications', 'notification_target',
+  'provider_accounts', 'provider_account', 'mcp_servers', 'mcp_server',
+  'setup_posture', 'setup_item',
+  'model_routing', 'model_route',
+  'pairing_posture', 'pairing_route',
+  'delegation_posture', 'delegation_route',
+  'security_posture', 'security_finding', 'support_bundles', 'support_bundle',
+  'media_posture', 'media_provider',
+  'sessions', 'session',
+  'settings', 'get_setting', 'set_setting',
   'reset_setting', 'workspace', 'workspace_categories', 'workspace_actions',
-  'workspace_action', 'run_workspace_action', 'tools', 'tool', 'connected_host', 'connected_host_status',
-  'connected_host_capability',
+  'workspace_action', 'run_workspace_action', 'tools', 'tool', 'release_evidence', 'release_evidence_artifact',
+  'release_readiness', 'release_readiness_item',
+  'operator_methods', 'operator_method',
+  'service_posture', 'service_endpoint',
+  'connected_host', 'connected_host_status', 'connected_host_capability',
 ] as const;
 
 const KEY_COMBO_PARAMETER_SCHEMA = {
@@ -19,53 +31,101 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   mode: {
     type: 'string',
     enum: AGENT_HARNESS_MODES,
-    description: 'Harness operation to perform.',
+    description: 'Harness operation. Start with summary or a plural catalog mode.',
   },
   query: {
     type: 'string',
-    description: 'Search text for slash-command, CLI mirror, panel, UI surface, keybinding, workspace action, model tool, setting, or connected-host capability catalogs; also lookup text for the matching single-item modes.',
+    description: 'Catalog search text or single-item lookup text.',
   },
   command: {
     type: 'string',
-    description: 'Full slash command string for mode command, workspace_action/run_workspace_action lookup, or run_command, for example "/settings get provider.model". In cli_command mode this may also hold a top-level CLI string such as "goodvibes-agent status --json".',
+    description: 'Slash command string, or CLI command string in cli_command mode.',
   },
   cliCommand: {
     type: 'string',
-    description: 'Top-level CLI command string for mode cli_command, for example "goodvibes-agent status --json" or "profiles list". target or query can also look up one CLI mirror when the exact command token is not known. This mode is read-only metadata/parse inspection.',
+    description: 'Top-level CLI command string for cli_command inspection.',
   },
   commandName: {
     type: 'string',
-    description: 'Slash command root without the leading slash for mode command or run_command, or a top-level CLI command token for cli_command. run_command can also resolve one slash command by target or query when the lookup is unique.',
+    description: 'Slash command root or top-level CLI command token.',
   },
   args: {
     type: 'array',
     items: { type: 'string' },
-    description: 'Slash command argument tokens for mode run_command when commandName is used.',
+    description: 'Arguments for run_command when commandName is used.',
+  },
+  channelId: {
+    type: 'string',
+    description: 'Channel id for channel mode.',
+  },
+  notificationTargetId: {
+    type: 'string',
+    description: 'Notification target id for notification_target mode.',
+  },
+  providerId: {
+    type: 'string',
+    description: 'Provider id for provider_account mode.',
+  },
+  mcpServerId: {
+    type: 'string',
+    description: 'MCP server id for mcp_server mode.',
+  },
+  setupItemId: {
+    type: 'string',
+    description: 'Setup item id for setup_item mode.',
+  },
+  modelRouteId: {
+    type: 'string',
+    description: 'Model route id or model key for model_route mode.',
+  },
+  pairingRouteId: {
+    type: 'string',
+    description: 'Pairing route id for pairing_route mode.',
+  },
+  delegationRouteId: {
+    type: 'string',
+    description: 'Delegation route id for delegation_route mode.',
+  },
+  findingId: {
+    type: 'string',
+    description: 'Security finding id for security_finding mode.',
+  },
+  bundlePath: {
+    type: 'string',
+    description: 'Workspace-relative bundle JSON path for support_bundle mode.',
+  },
+  mediaProviderId: {
+    type: 'string',
+    description: 'Voice or media provider id for media_provider mode.',
+  },
+  sessionId: {
+    type: 'string',
+    description: 'Saved session id for session mode.',
   },
   categoryId: {
     type: 'string',
-    description: 'Agent workspace category id for workspace action filtering or ui surface routing.',
+    description: 'Workspace category id.',
   },
   surfaceId: {
     type: 'string',
-    description: 'UI surface id for ui_surface or open_ui_surface modes. target or query can also look up one UI surface when the exact id is not known.',
+    description: 'UI surface id for ui_surface or open_ui_surface modes.',
   },
   panelId: {
     type: 'string',
-    description: 'Built-in panel id for panel or open_panel modes. target or query can also look up one panel when the exact id is not known.',
+    description: 'Built-in panel id for panel or open_panel modes.',
   },
   actionId: {
     type: 'string',
-    description: 'Agent workspace action id for workspace_action or run_workspace_action, or keybinding action id for keybinding/run_keybinding/set_keybinding/reset_keybinding. command, target, or query can also look up one workspace action; target or query can also look up one keybinding action.',
+    description: 'Workspace action id or keybinding action id.',
   },
   fields: {
     type: 'object',
     additionalProperties: { type: 'string' },
-    description: 'Field values for run_workspace_action when the workspace action opens an editor form.',
+    description: 'Editor field values for run_workspace_action.',
   },
   combo: {
     ...KEY_COMBO_PARAMETER_SCHEMA,
-    description: 'Single key combo for set_keybinding, for example { "key": "g", "ctrl": true }.',
+    description: 'Single key combo for set_keybinding.',
   },
   combos: {
     type: 'array',
@@ -74,11 +134,11 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   recordId: {
     type: 'string',
-    description: 'Selected Agent-local record id for selection-based local workspace operations.',
+    description: 'Selected Agent-local record id.',
   },
   key: {
     type: 'string',
-    description: 'Agent setting key for get_setting, set_setting, or reset_setting. target or query can also look up one setting when the exact key is not known.',
+    description: 'Agent setting key.',
   },
   value: {
     anyOf: [
@@ -86,23 +146,39 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
       { type: 'number' },
       { type: 'boolean' },
     ],
-    description: 'Setting value for set_setting. Strings, booleans, numbers, and enum strings are accepted. In run_keybinding, value can provide visible search text for search/history-search shortcut routes.',
+    description: 'Setting value, or visible search text for shortcut routes.',
   },
   target: {
     type: 'string',
-    description: 'Optional lookup target, such as a model-picker target, top-level CLI mirror/search text, panel id/search text, UI surface id/search text, workspace action id/search text, slash command root or invocation, setting key/search text, keybinding action/search text, model tool name/search text, or connected-host capability id/search text.',
+    description: 'Generic lookup target for single-item modes.',
+  },
+  methodId: {
+    type: 'string',
+    description: 'Public operator or Agent Knowledge method id.',
+  },
+  endpointId: {
+    type: 'string',
+    description: 'Connected service endpoint id.',
+  },
+  artifactId: {
+    type: 'string',
+    description: 'Release evidence artifact id.',
+  },
+  itemId: {
+    type: 'string',
+    description: 'Release readiness item id for mode release_readiness_item.',
   },
   capabilityId: {
     type: 'string',
-    description: 'Connected-host allowed or blocked capability id for mode connected_host_capability, such as agent-knowledge-read or connected-host-lifecycle.',
+    description: 'Connected-host capability id.',
   },
   toolName: {
     type: 'string',
-    description: 'First-class model tool name for mode tool, such as agent_harness or agent_local_registry.',
+    description: 'First-class model tool name.',
   },
   category: {
     type: 'string',
-    description: 'Setting category filter such as provider, behavior, tools, ui, tts, permissions, automation, or surfaces.',
+    description: 'Setting category filter.',
   },
   prefix: {
     type: 'string',
@@ -110,11 +186,11 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   },
   includeHidden: {
     type: 'boolean',
-    description: 'Include settings hidden from the Agent workspace because they are host-owned or non-Agent lifecycle settings.',
+    description: 'Include hidden settings in settings mode.',
   },
   includeParameters: {
     type: 'boolean',
-    description: 'Include model tool JSON schemas in tools mode, or workspace editor field schemas in workspace_actions mode.',
+    description: 'Include optional detail for discovery modes.',
   },
   limit: {
     type: 'number',
@@ -123,14 +199,14 @@ export const AGENT_HARNESS_PARAMETER_PROPERTIES = {
   pane: {
     type: 'string',
     enum: ['top', 'bottom'],
-    description: 'Preferred panel pane for open_panel when the current shell supports panel routing.',
+    description: 'Preferred pane for open_panel.',
   },
   confirm: {
     type: 'boolean',
-    description: 'Required true for set_setting, reset_setting, run_keybinding, run_command, open_panel, open_ui_surface, and executable or mutating run_workspace_action calls after an explicit user request.',
+    description: 'Required true for confirmed harness effects.',
   },
   explicitUserRequest: {
     type: 'string',
-    description: 'Exact user request or faithful short summary authorizing a setting mutation, keybinding change/action, harness UI routing, slash-command invocation, or workspace-action invocation.',
+    description: 'User request authorizing a confirmed harness effect.',
   },
 } as const;