@pellux/goodvibes-agent 1.1.7 → 1.3.0

package/src/tools/agent-harness-local-model-smoke.ts

@@ -0,0 +1,277 @@
+import type { CommandContext } from '../input/command-registry.ts';
+import type { AgentHarnessModelRoutingArgs, LocalModelServerDefaultEndpoint, LocalModelServerEndpoint, LocalModelSmokeTarget } from './agent-harness-model-routing-types.ts';
+import { previewHarnessText } from './agent-harness-text.ts';
+import { readLimit, readRecord, readString } from './agent-harness-model-routing-utils.ts';
+import { collectLocalServerEndpointCandidates, describeLocalServerEndpoint, isPrivateOrLocalUrl, localEndpointSmokeRoute, localModelServerDefaults, parseUrlCandidate } from './agent-harness-local-model-endpoints.ts';
+
+function localModelSmokeTargetFromEndpoint(endpoint: LocalModelServerEndpoint): LocalModelSmokeTarget {
+  return {
+    kind: endpoint.kind,
+    id: endpoint.id,
+    label: `Local model server ${endpoint.baseUrl}`,
+    providerId: endpoint.providerId,
+    stack: endpoint.stack,
+    baseUrl: endpoint.baseUrl,
+    modelsUrl: endpoint.modelsUrl,
+    smokeCommand: endpoint.smokeCommand,
+    smokeRoute: endpoint.smokeRoute,
+    refreshRoute: endpoint.refreshRoute,
+    addProviderRoute: endpoint.addProviderRoute,
+    source: endpoint.sources.join(', ') || 'local-endpoint',
+    notes: endpoint.notes,
+  };
+}
+
+function localModelSmokeTargetFromDefault(endpoint: LocalModelServerDefaultEndpoint): LocalModelSmokeTarget {
+  return {
+    kind: 'suggested-local-server',
+    id: endpoint.id,
+    label: endpoint.label,
+    providerId: null,
+    stack: endpoint.stack,
+    baseUrl: endpoint.baseUrl,
+    modelsUrl: endpoint.modelsUrl,
+    smokeCommand: endpoint.smokeCommand,
+    smokeRoute: localEndpointSmokeRoute(endpoint.id),
+    refreshRoute: 'agent_harness mode:"run_command" command:"/refresh-models" confirm:true explicitUserRequest:"Refresh models after verifying the local server."',
+    addProviderRoute: endpoint.addProviderRoute,
+    source: 'suggested-default',
+    notes: [endpoint.startHint],
+  };
+}
+
+function localSmokeTargetSearchText(target: LocalModelSmokeTarget): string {
+  return [
+    target.kind,
+    target.id,
+    target.label,
+    target.providerId ?? '',
+    target.stack ?? '',
+    target.baseUrl,
+    target.modelsUrl,
+    target.source,
+    ...target.notes,
+  ].join('\n').toLowerCase();
+}
+
+function localModelSmokeLookup(args: AgentHarnessModelRoutingArgs): string {
+  const fields = readRecord(args.fields);
+  return readString(args.modelRouteId)
+    || readString(args.target)
+    || readString(args.query)
+    || readString(fields.endpointId)
+    || readString(fields.modelRouteId)
+    || readString(fields.baseUrl)
+    || readString(fields.modelsUrl);
+}
+
+function localModelSmokeTargets(context: CommandContext, args: AgentHarnessModelRoutingArgs): Record<string, unknown> | readonly LocalModelSmokeTarget[] {
+  const endpoints = collectLocalServerEndpointCandidates(context)
+    .map((endpoint) => localModelSmokeTargetFromEndpoint(describeLocalServerEndpoint(endpoint, true)));
+  const defaults = localModelServerDefaults().map(localModelSmokeTargetFromDefault);
+  const lookup = localModelSmokeLookup(args);
+  const allTargets = [...endpoints, ...defaults];
+  if (lookup) {
+    const normalized = lookup.toLowerCase();
+    const exact = allTargets.filter((target) => target.id === lookup || target.baseUrl === lookup || target.modelsUrl === lookup);
+    if (exact.length === 1) return exact;
+    if (exact.length > 1) {
+      return {
+        status: 'ambiguous',
+        input: lookup,
+        candidates: exact.slice(0, 8).map((target) => ({
+          kind: target.kind,
+          id: target.id,
+          label: target.label,
+          baseUrl: target.baseUrl,
+          modelsUrl: target.modelsUrl,
+        })),
+      };
+    }
+    const searched = allTargets.filter((target) => localSmokeTargetSearchText(target).includes(normalized));
+    if (searched.length === 1) return searched;
+    if (searched.length > 1) {
+      return {
+        status: 'ambiguous',
+        input: lookup,
+        candidates: searched.slice(0, 8).map((target) => ({
+          kind: target.kind,
+          id: target.id,
+          label: target.label,
+          baseUrl: target.baseUrl,
+          modelsUrl: target.modelsUrl,
+        })),
+      };
+    }
+    return {
+      status: 'missing_lookup',
+      input: lookup,
+      usage: 'Unknown local model endpoint. Use models action:"local" includeParameters:true to inspect local endpoint ids, or omit the lookup to check detected/default local servers.',
+    };
+  }
+  const pool = endpoints.length ? endpoints : defaults;
+  return pool.slice(0, readLimit(args.limit, 4));
+}
+
+function readSmokeTimeoutMs(value: unknown): number {
+  const parsed = typeof value === 'string' && value.trim() ? Number(value) : value;
+  if (typeof parsed !== 'number' || !Number.isFinite(parsed)) return 1500;
+  return Math.max(250, Math.min(10000, Math.trunc(parsed)));
+}
+
+function localSmokeNetworkScope(modelsUrl: string): { readonly allowed: boolean; readonly scope: string; readonly reason?: string } {
+  const url = parseUrlCandidate(modelsUrl);
+  if (!url || !/^https?:$/.test(url.protocol)) return { allowed: false, scope: 'invalid-url', reason: 'The model-list URL is not a valid HTTP(S) URL.' };
+  const host = url.hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (host === '0.0.0.0') {
+    return { allowed: false, scope: 'bind-all-host', reason: '0.0.0.0 is a bind address, not a client URL. Use 127.0.0.1 or the intended LAN host.' };
+  }
+  if (!isPrivateOrLocalUrl(url.href)) {
+    return { allowed: false, scope: 'non-local-host', reason: 'Local model smoke only probes loopback, local-name, or private LAN endpoints.' };
+  }
+  if (host === 'localhost' || host === '127.0.0.1' || host === '::1') return { allowed: true, scope: 'loopback' };
+  if (host.endsWith('.local') || !host.includes('.')) return { allowed: true, scope: 'local-name' };
+  return { allowed: true, scope: 'private-lan' };
+}
+
+function extractModelIdsFromPayload(payload: unknown): readonly string[] {
+  const record = readRecord(payload);
+  const candidates = Array.isArray(record.data)
+    ? record.data
+    : Array.isArray(record.models)
+      ? record.models
+      : Array.isArray(payload)
+        ? payload
+        : [];
+  const ids = candidates.map((entry) => {
+    if (typeof entry === 'string') return entry;
+    const item = readRecord(entry);
+    return readString(item.id) || readString(item.name) || readString(item.model);
+  }).filter(Boolean);
+  return [...new Set(ids)].slice(0, 12);
+}
+
+function safeSmokeError(error: unknown): string {
+  const message = error instanceof Error ? error.message : String(error);
+  return previewHarnessText(message.replace(/https?:\/\/\S+/g, '[redacted-url]'), 180);
+}
+
+async function smokeOneLocalModelTarget(target: LocalModelSmokeTarget, timeoutMs: number): Promise<Record<string, unknown>> {
+  const network = localSmokeNetworkScope(target.modelsUrl);
+  if (!network.allowed) {
+    return {
+      ...target,
+      status: 'blocked',
+      liveProbe: 'confirmed',
+      networkScope: network.scope,
+      failure: network.reason,
+      nextActions: ['Inspect the endpoint route and correct the base URL before running smoke again.'],
+    };
+  }
+
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), timeoutMs);
+  const started = Date.now();
+  try {
+    const response = await fetch(target.modelsUrl, {
+      method: 'GET',
+      headers: { Accept: 'application/json' },
+      signal: controller.signal,
+    });
+    const elapsedMs = Date.now() - started;
+    const contentType = response.headers.get('content-type') ?? '';
+    const text = await response.text();
+    let payload: unknown = null;
+    let jsonValid = false;
+    try {
+      payload = text ? JSON.parse(text) : null;
+      jsonValid = true;
+    } catch {
+      jsonValid = false;
+    }
+    const modelIds = jsonValid ? extractModelIdsFromPayload(payload) : [];
+    const status = !response.ok
+      ? 'http-error'
+      : !jsonValid
+        ? 'invalid-json'
+        : modelIds.length === 0
+          ? 'no-models'
+          : 'passed';
+    return {
+      ...target,
+      status,
+      liveProbe: 'confirmed',
+      networkScope: network.scope,
+      httpStatus: response.status,
+      contentType,
+      elapsedMs,
+      jsonValid,
+      modelCount: modelIds.length,
+      sampleModelIds: modelIds.slice(0, 5),
+      success: status === 'passed',
+      nextActions: status === 'passed'
+        ? ['Refresh the model catalog, then run a local benchmark before changing the default model.']
+        : ['Start or fix the local server, confirm /v1/models returns model ids, then retry this smoke check.'],
+    };
+  } catch (error) {
+    const elapsedMs = Date.now() - started;
+    const aborted = controller.signal.aborted;
+    return {
+      ...target,
+      status: aborted ? 'timeout' : 'unreachable',
+      liveProbe: 'confirmed',
+      networkScope: network.scope,
+      elapsedMs,
+      timeoutMs,
+      success: false,
+      failure: aborted ? `Timed out after ${timeoutMs}ms.` : safeSmokeError(error),
+      nextActions: ['Start the local server, load at least one model, verify the base URL, then retry this smoke check.'],
+    };
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function runLocalModelServerSmoke(context: CommandContext, args: AgentHarnessModelRoutingArgs): Promise<Record<string, unknown>> {
+  const targets = localModelSmokeTargets(context, args);
+  if (!Array.isArray(targets)) {
+    return {
+      kind: 'local-model-smoke',
+      liveProbe: 'not-run',
+      ...targets,
+      policy: 'No local model endpoint was probed because the requested endpoint lookup did not resolve exactly.',
+    };
+  }
+  if (targets.length === 0) {
+    return {
+      kind: 'local-model-smoke',
+      status: 'no-candidates',
+      liveProbe: 'not-run',
+      endpoints: [],
+      nextActions: ['Use the local model cookbook to start a local server or configure a local provider endpoint.'],
+      cookbookRoute: 'models action:"local" includeParameters:true',
+      policy: 'No local model endpoint was probed because no candidate endpoints were available.',
+    };
+  }
+  const timeoutMs = readSmokeTimeoutMs(args.timeoutMs);
+  const checkedAt = new Date().toISOString();
+  const results = await Promise.all(targets.map((target) => smokeOneLocalModelTarget(target, timeoutMs)));
+  const passed = results.filter((result) => result.success === true);
+  const blocked = results.filter((result) => result.status === 'blocked');
+  return {
+    kind: 'local-model-smoke',
+    status: passed.length > 0 ? 'ready' : blocked.length === results.length ? 'blocked' : 'needs-attention',
+    liveProbe: 'confirmed',
+    checkedAt,
+    timeoutMs,
+    endpointCount: results.length,
+    passedCount: passed.length,
+    failedCount: results.length - passed.length,
+    endpoints: results,
+    nextActions: passed.length > 0
+      ? ['Refresh the model catalog and run the local benchmark action before changing the default route.']
+      : ['Start a local model server, load one model, and rerun this confirmed smoke check.'],
+    cookbookRoute: 'models action:"local" includeParameters:true',
+    policy: 'Confirmed read-only local model smoke. Agent only sends bounded GET requests to discovered or suggested local/private model-list endpoints; it does not add providers, refresh catalogs, benchmark, download models, or change routes.',
+  };
+}

package/src/tools/agent-harness-local-model-url.ts

@@ -0,0 +1,78 @@
+export function localStackFor(value: string): string | null {
+  const normalized = value.toLowerCase();
+  if (/ollama[-_\s]?cloud/.test(normalized)) return null;
+  if (/\bollama\b/.test(normalized)) return 'ollama';
+  if (/llama[.-]?cpp|llamacpp/.test(normalized)) return 'llama.cpp';
+  if (/\bvllm\b/.test(normalized)) return 'vllm';
+  if (/lm[-_\s]?studio/.test(normalized)) return 'openai-compatible';
+  if (/localai|text-generation-inference|\btgi\b/.test(normalized)) return 'openai-compatible';
+  if (/localhost|127\.0\.0\.1|\[?::1\]?/.test(normalized)) return 'openai-compatible';
+  if (/openai-compatible|openai compatible|custom-provider|custom provider/.test(normalized)) return 'openai-compatible';
+  return null;
+}
+
+export function cleanUrlCandidate(value: string): string {
+  return value.trim().replace(/[),.;]+$/g, '');
+}
+
+export function extractUrls(value: string): readonly string[] {
+  const matches = value.match(/https?:\/\/[^\s"'`<>]+/gi) ?? [];
+  return [...new Set(matches.map(cleanUrlCandidate).filter(Boolean))];
+}
+
+export function parseUrlCandidate(raw: string): URL | null {
+  const trimmed = cleanUrlCandidate(raw);
+  if (!trimmed) return null;
+  const withScheme = /^[a-z][a-z0-9+.-]*:\/\//i.test(trimmed) ? trimmed : `http://${trimmed}`;
+  try {
+    return new URL(withScheme);
+  } catch {
+    return null;
+  }
+}
+
+export function isPrivateOrLocalHost(hostname: string): boolean {
+  const host = hostname.replace(/^\[|\]$/g, '').toLowerCase();
+  if (!host) return false;
+  if (host === 'localhost' || host === '0.0.0.0' || host === '::1') return true;
+  if (host.endsWith('.local')) return true;
+  if (host.includes(':')) return host.startsWith('fc') || host.startsWith('fd') || host.startsWith('fe80:');
+  const octets = host.split('.').map((entry) => Number(entry));
+  if (octets.length === 4 && octets.every((entry) => Number.isInteger(entry) && entry >= 0 && entry <= 255)) {
+    const [first, second] = octets as [number, number, number, number];
+    return first === 10
+      || first === 127
+      || (first === 172 && second >= 16 && second <= 31)
+      || (first === 192 && second === 168)
+      || (first === 169 && second === 254)
+      || first === 0;
+  }
+  return !host.includes('.');
+}
+
+export function isPrivateOrLocalUrl(raw: string): boolean {
+  const url = parseUrlCandidate(raw);
+  if (!url || !/^https?:$/.test(url.protocol)) return false;
+  return isPrivateOrLocalHost(url.hostname);
+}
+
+export function normalizeLocalBaseUrl(raw: string, stackHint?: string | null): string | null {
+  const url = parseUrlCandidate(raw);
+  if (!url || !/^https?:$/.test(url.protocol)) return null;
+  const stack = stackHint ?? localStackFor(raw) ?? (isPrivateOrLocalHost(url.hostname) ? 'openai-compatible' : null);
+  if (!isPrivateOrLocalUrl(url.href)) return null;
+
+  let pathname = url.pathname.replace(/\/+$/g, '');
+  if (pathname.endsWith('/models')) pathname = pathname.slice(0, -'/models'.length);
+  if (pathname.endsWith('/api/tags')) pathname = pathname.slice(0, -'/api/tags'.length);
+  const needsOpenAiPath = stack === 'ollama' || stack === 'llama.cpp' || stack === 'vllm' || stack === 'openai-compatible';
+  if (needsOpenAiPath && (!pathname || pathname === '/')) pathname = '/v1';
+  url.pathname = pathname || '';
+  url.search = '';
+  url.hash = '';
+  return url.toString().replace(/\/+$/g, '');
+}
+
+export function modelsUrlFor(baseUrl: string): string {
+  return `${baseUrl.replace(/\/+$/g, '')}/models`;
+}

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

@@ -1,6 +1,7 @@
 import { buildAgentWorkspaceVoiceMediaReadiness } from '../input/agent-workspace-voice-media.ts';
 import type { AgentWorkspaceVoiceMediaProviderStatus } from '../input/agent-workspace-voice-media.ts';
 import type { CommandContext } from '../input/command-registry.ts';
+import { certifiedDeviceLiveRecords, deviceLiveReadModelSnapshot } from './agent-harness-device-live-read-models.ts';
 import { previewHarnessText } from './agent-harness-text.ts';
 
 export interface AgentHarnessMediaArgs {
@@ -16,6 +17,8 @@ type MediaProviderResolution =
   | { readonly status: 'ambiguous'; readonly input: string; readonly candidates: readonly Record<string, unknown>[] }
   | { readonly status: 'missing_lookup'; readonly usage: string };
 
+type VoiceWorkflowStatus = 'ready' | 'attention' | 'setup-needed' | 'not-published';
+
 interface RuntimeProviderStatus {
   readonly id: string;
   readonly state: string;
@@ -23,6 +26,21 @@ interface RuntimeProviderStatus {
   readonly detail?: string;
 }
 
+interface VoiceInteractionWorkflow {
+  readonly id: string;
+  readonly label: string;
+  readonly status: VoiceWorkflowStatus;
+  readonly userOutcome: string;
+  readonly summary: string;
+  readonly nextStep: string;
+  readonly capabilities: readonly string[];
+  readonly modelRoute: string;
+  readonly userRoute?: string;
+  readonly setupRoutes: readonly string[];
+  readonly evidence: Record<string, unknown>;
+  readonly policy: string;
+}
+
 function readString(value: unknown): string {
   return typeof value === 'string' ? value.trim() : '';
 }
@@ -70,6 +88,198 @@ function providerSearchText(provider: AgentWorkspaceVoiceMediaProviderStatus, ru
   ].join('\n').toLowerCase();
 }
 
+function voiceWorkflowSearchText(workflow: VoiceInteractionWorkflow): string {
+  return [
+    workflow.id,
+    workflow.label,
+    workflow.status,
+    workflow.userOutcome,
+    workflow.summary,
+    workflow.nextStep,
+    workflow.modelRoute,
+    workflow.userRoute ?? '',
+    ...workflow.capabilities,
+  ].join('\n').toLowerCase();
+}
+
+function voiceWorkflowMatches(workflow: VoiceInteractionWorkflow, query: string): boolean {
+  if (!query) return true;
+  const text = voiceWorkflowSearchText(workflow);
+  if (text.includes(query)) return true;
+  const tokens = query.split(/\s+/).map((token) => token.trim()).filter(Boolean);
+  return tokens.length > 0 && tokens.every((token) => text.includes(token));
+}
+
+function voiceWorkflowSummary(workflows: readonly VoiceInteractionWorkflow[]): Record<string, unknown> {
+  return {
+    total: workflows.length,
+    ready: workflows.filter((workflow) => workflow.status === 'ready').length,
+    attention: workflows.filter((workflow) => workflow.status === 'attention').length,
+    setupNeeded: workflows.filter((workflow) => workflow.status === 'setup-needed').length,
+    notPublished: workflows.filter((workflow) => workflow.status === 'not-published').length,
+    primaryNextStep: workflows.find((workflow) => workflow.status !== 'ready')?.nextStep
+      ?? 'Voice workflows are ready; keep effects on explicit user-visible routes.',
+  };
+}
+
+function hasReadyVoiceFeature(readiness: ReturnType<typeof buildReadiness>, featureIds: readonly string[]): boolean {
+  return readiness.voiceProviders.some((provider) => (
+    provider.setupState === 'ready'
+    && featureIds.some((feature) => provider.features.includes(feature))
+  ));
+}
+
+function hasRegisteredVoiceFeature(readiness: ReturnType<typeof buildReadiness>, featureIds: readonly string[]): boolean {
+  return readiness.voiceProviders.some((provider) => featureIds.some((feature) => provider.features.includes(feature)));
+}
+
+function buildVoiceInteractionWorkflows(
+  context: CommandContext,
+  readiness: ReturnType<typeof buildReadiness>,
+): readonly VoiceInteractionWorkflow[] {
+  const liveDevice = deviceLiveReadModelSnapshot(context);
+  const pushToTalkRecords = certifiedDeviceLiveRecords(liveDevice, 'push-to-talk', ['push to talk', 'speech input', 'microphone']);
+  const transcriptionRecords = certifiedDeviceLiveRecords(liveDevice, 'voice-memo-transcription', ['voice memo', 'speech-to-text', 'audio transcription']);
+  const spokenResponseRecords = certifiedDeviceLiveRecords(liveDevice, 'spoken-responses', ['tts', 'spoken response', 'speaker']);
+  const wakeRecords = certifiedDeviceLiveRecords(liveDevice, 'wake-and-speak', ['wake word', 'always listening']);
+  const voiceEnabled = readConfigBoolean(context, 'ui.voiceEnabled', false);
+  const spokenTurnRuntime = typeof context.submitSpokenInput === 'function';
+  const stopSpokenOutputRuntime = typeof context.stopSpokenOutput === 'function';
+  const transcribeRuntime = typeof context.platform.voiceService?.transcribe === 'function';
+  const speechInputReady = hasReadyVoiceFeature(readiness, ['stt', 'realtime']);
+  const speechInputRegistered = hasRegisteredVoiceFeature(readiness, ['stt', 'realtime']);
+  const selectedTtsReady = readiness.selectedTtsProviderStatus === 'ready';
+  const spokenReady = spokenResponseRecords.length > 0 || (spokenTurnRuntime && selectedTtsReady && readiness.ttsVoiceConfigured);
+  const spokenAttention = spokenTurnRuntime && selectedTtsReady && !readiness.ttsVoiceConfigured;
+  const pushToTalkReady = pushToTalkRecords.length > 0 || (voiceEnabled && spokenTurnRuntime && speechInputReady);
+  const pushToTalkAttention = voiceEnabled && (spokenTurnRuntime || speechInputRegistered);
+  const transcriptionReady = transcriptionRecords.length > 0 || (transcribeRuntime && speechInputReady);
+  const transcriptionAttention = transcribeRuntime || speechInputRegistered;
+
+  return [
+    {
+      id: 'push-to-talk',
+      label: 'Push-to-talk input',
+      status: pushToTalkReady ? 'ready' : pushToTalkAttention ? 'attention' : 'setup-needed',
+      userOutcome: 'Speak a short prompt when the local voice surface and speech-input provider are ready.',
+      summary: pushToTalkReady
+        ? pushToTalkRecords.length > 0 ? 'The SDK/daemon published a certified push-to-talk route with permission-scoped microphone evidence.' : 'Voice surface, spoken-turn runtime, and a ready STT/realtime provider are available.'
+        : pushToTalkAttention
+          ? 'Some voice input pieces are present, but the full push-to-talk route is not ready.'
+          : 'Voice input needs the voice surface plus a ready STT or realtime provider.',
+      nextStep: pushToTalkReady
+        ? 'Use the visible voice surface when the user asks to speak to the assistant.'
+        : 'Review /voice and media provider posture before presenting push-to-talk as available.',
+      capabilities: ['push-to-talk', 'speech input', 'stt', 'realtime voice'],
+      modelRoute: 'agent_harness mode:"media_posture" query:"push to talk" includeParameters:true',
+      userRoute: '/voice review',
+      setupRoutes: [
+        'settings action:"get" query:"ui.voiceEnabled" includeParameters:true',
+        'agent_harness mode:"media_posture" query:"stt realtime" includeParameters:true',
+      ],
+      evidence: {
+        voiceSurfaceEnabled: voiceEnabled,
+        spokenTurnRuntime,
+        speechInputReady,
+        speechInputRegistered,
+        ...(pushToTalkRecords.length > 0 ? { certifiedLiveRecords: pushToTalkRecords.slice(0, 5) } : {}),
+      },
+      policy: 'Voice input stays a visible local operator surface; provider setup and transcript submission are separate explicit routes.',
+    },
+    {
+      id: 'voice-memo-transcription',
+      label: 'Voice memo transcription',
+      status: transcriptionReady ? 'ready' : transcriptionAttention ? 'attention' : 'setup-needed',
+      userOutcome: 'Transcribe an audio note only when a speech-to-text provider and runtime route are both present.',
+      summary: transcriptionReady
+        ? transcriptionRecords.length > 0 ? 'The SDK/daemon published a certified voice memo transcription route.' : 'Speech-to-text provider and voiceService.transcribe are available.'
+        : transcriptionAttention
+          ? 'A speech-to-text provider or runtime route is present, but transcription is not fully ready.'
+          : 'No ready speech-to-text transcription route is available.',
+      nextStep: transcriptionReady
+        ? 'Route audio transcription through reviewed media or connected-host voice routes when the user supplies audio.'
+        : 'Configure a provider with STT capability and confirm the runtime exposes voiceService.transcribe.',
+      capabilities: ['voice memo', 'speech-to-text', 'audio transcription'],
+      modelRoute: 'agent_harness mode:"media_posture" query:"voice memo transcription" includeParameters:true',
+      setupRoutes: [
+        'agent_harness mode:"media_posture" query:"stt" includeParameters:true',
+        'host action:"methods" query:"voice.stt"',
+      ],
+      evidence: {
+        transcribeRuntime,
+        speechInputReady,
+        speechInputRegistered,
+        ...(transcriptionRecords.length > 0 ? { certifiedLiveRecords: transcriptionRecords.slice(0, 5) } : {}),
+      },
+      policy: 'Audio bytes are not printed into chat; transcription must use reviewed media or connected-host voice routes.',
+    },
+    {
+      id: 'spoken-responses',
+      label: 'Spoken responses',
+      status: spokenReady ? 'ready' : spokenAttention ? 'attention' : 'setup-needed',
+      userOutcome: 'Play an assistant answer aloud with a predictable TTS provider and voice.',
+      summary: spokenReady
+        ? spokenResponseRecords.length > 0 ? 'The SDK/daemon published a certified spoken-response route.' : 'Spoken-turn runtime, selected TTS provider, and voice setting are ready.'
+        : spokenAttention
+          ? 'Spoken-turn runtime and provider are ready, but the exact voice is not configured.'
+          : 'Spoken responses need a ready selected TTS provider and runtime spoken-turn route.',
+      nextStep: spokenReady
+        ? 'Use /tts only when the user asks for spoken output.'
+        : 'Choose a ready TTS provider and voice, then verify the runtime exposes submitSpokenInput.',
+      capabilities: ['tts', 'spoken answer', 'stop spoken output'],
+      modelRoute: 'agent_harness mode:"media_posture" query:"spoken responses" includeParameters:true',
+      userRoute: '/tts <prompt>',
+      setupRoutes: [
+        'agent_harness mode:"open_ui_surface" surfaceId:"tts-provider-picker" confirm:true explicitUserRequest:"..."',
+        'agent_harness mode:"open_ui_surface" surfaceId:"tts-voice-picker" confirm:true explicitUserRequest:"..."',
+      ],
+      evidence: {
+        spokenTurnRuntime,
+        stopSpokenOutputRuntime,
+        selectedTtsProviderStatus: readiness.selectedTtsProviderStatus,
+        ttsVoiceConfigured: readiness.ttsVoiceConfigured,
+        ...(spokenResponseRecords.length > 0 ? { certifiedLiveRecords: spokenResponseRecords.slice(0, 5) } : {}),
+      },
+      policy: 'Spoken turns submit normal assistant prompts and may call model/speech providers; playback stop is local runtime control.',
+    },
+    {
+      id: 'wake-and-speak',
+      label: 'Wake and speak',
+      status: wakeRecords.length > 0 ? 'ready' : 'not-published',
+      userOutcome: 'Use wake-word or always-listening input only after a permission-scoped runtime contract exists.',
+      summary: wakeRecords.length > 0
+        ? 'The SDK/daemon published certified wake-word evidence with permission scope, receipt metadata, and exact control routes.'
+        : 'Wake-word or always-listening voice capture is not published by the current Agent runtime contract.',
+      nextStep: wakeRecords.length > 0
+        ? 'Inspect the certified wake-word route and keep microphone capture on visible permission controls.'
+        : 'Use explicit voice input or /tts until a wake-word route is published with visible permission controls.',
+      capabilities: ['wake word', 'always listening', 'permission repair'],
+      modelRoute: wakeRecords[0]?.modelRoute ?? 'agent_harness mode:"media_posture" query:"wake word" includeParameters:true',
+      setupRoutes: [
+        ...wakeRecords.slice(0, 3).map((record) => record.modelRoute),
+        'agent_harness mode:"media_posture" query:"push to talk" includeParameters:true',
+        'agent_harness mode:"pairing_posture" query:"device" includeParameters:true',
+      ],
+      evidence: {
+        publishedByCurrentAgentContract: wakeRecords.length > 0,
+        ...(wakeRecords.length > 0 ? { certifiedLiveRecords: wakeRecords.slice(0, 5) } : {}),
+      },
+      policy: 'Agent does not claim always-listening behavior without an explicit permission-scoped runtime contract and certified SDK/daemon receipt evidence.',
+    },
+  ];
+}
+
+function describeVoiceWorkflow(workflow: VoiceInteractionWorkflow, includeParameters: boolean): Record<string, unknown> {
+  if (includeParameters) return { ...workflow };
+  return {
+    workflowId: workflow.id,
+    label: workflow.label,
+    status: workflow.status,
+    summary: previewHarnessText(workflow.summary),
+    modelRoute: workflow.modelRoute,
+  };
+}
+
 function describeProviderCandidate(provider: AgentWorkspaceVoiceMediaProviderStatus): Record<string, unknown> {
   return {
     mediaProviderId: `${provider.domain}:${provider.id}`,
@@ -124,7 +334,7 @@ function describeProvider(
           inspectPosture: 'agent_harness mode:"media_posture"',
           inspectProvider: 'agent_harness mode:"media_provider"',
           generateMedia: 'agent_media_generate with confirm:true and explicitUserRequest',
-          ttsSettings: 'agent_harness mode:"settings", mode:"get_setting", mode:"set_setting" for tts.provider, tts.voice, tts.llmProvider, and tts.llmModel',
+          ttsSettings: 'settings action:"list|get|set" for tts.provider, tts.voice, tts.llmProvider, and tts.llmModel',
         },
         policy: {
           effect: 'read-only',
@@ -179,12 +389,14 @@ function buildReadiness(context: CommandContext) {
 
 export function mediaPostureCatalogStatus(context: CommandContext): Record<string, unknown> {
   const readiness = buildReadiness(context);
+  const voiceWorkflows = buildVoiceInteractionWorkflows(context, readiness);
   return {
     modes: ['media_posture', 'media_provider'],
     voiceProviders: readiness.voiceProviders.length,
     mediaProviders: readiness.mediaProviders.length,
     readyVoiceProviders: readiness.readyVoiceProviderCount,
     readyMediaProviders: readiness.readyMediaProviderCount,
+    voiceWorkflowSummary: voiceWorkflowSummary(voiceWorkflows),
     readOnly: true,
   };
 }
@@ -199,9 +411,14 @@ export async function mediaPostureSummary(context: CommandContext, args: AgentHa
     ...readiness.mediaProviders.map((provider) => ({ provider, runtimeStatus: mediaStatuses.get(provider.id) })),
   ];
   const query = readString(args.query).toLowerCase();
+  const limit = readLimit(args.limit, 100);
+  const voiceWorkflows = buildVoiceInteractionWorkflows(context, readiness);
   const filtered = providers
     .filter(({ provider, runtimeStatus }) => !query || providerSearchText(provider, runtimeStatus).includes(query))
-    .slice(0, readLimit(args.limit, 100));
+    .slice(0, limit);
+  const filteredVoiceWorkflows = voiceWorkflows
+    .filter((workflow) => voiceWorkflowMatches(workflow, query))
+    .slice(0, limit);
   return {
     status: 'available',
     summary: {
@@ -215,6 +432,8 @@ export async function mediaPostureSummary(context: CommandContext, args: AgentHa
       ttsResponseRouteConfigured: readiness.ttsResponseRouteConfigured,
       voiceSurfaceEnabled: readConfigBoolean(context, 'ui.voiceEnabled', false),
       browserToolState: readiness.browserToolState,
+      voiceWorkflows: voiceWorkflowSummary(voiceWorkflows),
+      returnedVoiceWorkflows: filteredVoiceWorkflows.length,
       artifactStoreAvailable: Boolean(context.platform.artifactStore),
       ttsProviderSetting: readConfigString(context, 'tts.provider') || null,
       ttsVoiceSettingConfigured: readConfigString(context, 'tts.voice').length > 0,
@@ -223,6 +442,7 @@ export async function mediaPostureSummary(context: CommandContext, args: AgentHa
     providers: filtered.map(({ provider, runtimeStatus }) => describeProvider(provider, runtimeStatus, {
       includeParameters: args.includeParameters === true,
     })),
+    voiceWorkflows: filteredVoiceWorkflows.map((workflow) => describeVoiceWorkflow(workflow, args.includeParameters === true)),
     returned: filtered.length,
     total: providers.length,
     policy: 'Read-only voice/media posture. Media generation, voice enable/disable, TTS setting changes, and bundle export stay confirmation-gated through first-class tools, settings modes, workspace actions, or slash-command mirrors.',
@@ -232,6 +452,7 @@ export async function mediaPostureSummary(context: CommandContext, args: AgentHa
       singleProviderMode: 'media_provider',
       ttsProviderPicker: 'agent_harness mode:"open_ui_surface" surfaceId:"tts-provider-picker" confirm:true explicitUserRequest:"..."',
       ttsVoicePicker: 'agent_harness mode:"open_ui_surface" surfaceId:"tts-voice-picker" confirm:true explicitUserRequest:"..."',
+      voiceWorkflowPosture: 'agent_harness mode:"media_posture" query:"push to talk" includeParameters:true',
       commands: ['/media providers', '/voice review', '/tts <prompt>', '/image <path>'],
     } } : {}),
   };