@softize/opus 9.0.9 → 9.1.1

package/src/ui/components/primitives/ask.tsx

@@ -0,0 +1,186 @@
+import * as React from 'react'
+import type { AskAnswer, AskQuestion } from '../../../core/index.ts'
+import { cn } from '../../lib/cn.ts'
+import { Button } from './button.tsx'
+import { Card } from './card.tsx'
+import { Input } from './input.tsx'
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from './tooltip.tsx'
+
+export interface AskProps {
+  /** Uma a quatro perguntas do contrato de elicitação. */
+  questions: AskQuestion[]
+  /** Respostas controladas, na mesma ordem de `questions`. Entradas ausentes são vazias. */
+  answers: AskAnswer[]
+  onChange: (answers: AskAnswer[]) => void
+  /** Dispara somente quando toda pergunta tem uma opção ou texto livre. */
+  onSubmit: (answers: AskAnswer[]) => void
+  disabled?: boolean
+  busy?: boolean
+  className?: string
+}
+
+function answerFor(question: AskQuestion, answer?: AskAnswer): AskAnswer {
+  const optionLabels = new Set(question.options.map((option) => option.label))
+  const selected = (answer?.selected ?? []).filter((label) => optionLabels.has(label))
+  return {
+    header: question.header?.trim() || question.question,
+    selected: question.multiSelect ? selected : selected.slice(0, 1),
+    ...(answer?.text === undefined ? {} : { text: answer.text }),
+  }
+}
+
+function isAnswered(answer: AskAnswer): boolean {
+  return answer.selected.length > 0 || (answer.text?.trim() ?? '') !== ''
+}
+
+/** Elicitação estruturada controlada. Não executa transporte nem mantém estado de domínio. */
+export function Ask({
+  questions,
+  answers,
+  onChange,
+  onSubmit,
+  disabled = false,
+  busy = false,
+  className,
+}: AskProps): React.ReactElement {
+  const id = React.useId()
+  const questionSignature = JSON.stringify(questions)
+  const [submittedSignature, setSubmittedSignature] = React.useState<string>()
+  const submitted = submittedSignature === questionSignature
+  const normalized = questions.map((question, index) => answerFor(question, answers[index]))
+  const validCount = questions.length >= 1 && questions.length <= 4
+  const allAnswered = validCount && normalized.every(isAnswered)
+  const locked = disabled || busy
+
+  const changeAt = (index: number, next: AskAnswer): void => {
+    const nextAnswers = [...normalized]
+    nextAnswers[index] = next
+    onChange(nextAnswers)
+  }
+
+  return (
+    <Card
+      asChild
+      className={cn('p-4', className)}
+      aria-busy={busy || undefined}
+      aria-disabled={disabled || undefined}
+    >
+      <form
+        data-slot="ask"
+        noValidate
+        onSubmit={(event) => {
+          event.preventDefault()
+          setSubmittedSignature(questionSignature)
+          if (allAnswered && !locked) onSubmit(normalized)
+        }}
+      >
+        <TooltipProvider>
+          <div className="space-y-4">
+            {questions.map((question, questionIndex) => {
+              const answer = normalized[questionIndex]
+              const questionId = `${id}-question-${questionIndex}`
+              const errorId = `${id}-error-${questionIndex}`
+              const invalid = submitted && !isAnswered(answer)
+
+              return (
+                <fieldset key={questionId} disabled={locked} className="min-w-0 space-y-2.5">
+                  <legend id={questionId} className="text-sm font-medium text-foreground">
+                    {question.question}
+                  </legend>
+                  <div
+                    role={question.multiSelect ? 'group' : 'radiogroup'}
+                    aria-labelledby={questionId}
+                    aria-describedby={invalid ? errorId : undefined}
+                    className="flex flex-wrap gap-2"
+                    onKeyDown={question.multiSelect ? undefined : (event) => {
+                      if (!['ArrowLeft', 'ArrowRight', 'ArrowUp', 'ArrowDown'].includes(event.key)) return
+                      const radios = Array.from(
+                        event.currentTarget.querySelectorAll<HTMLButtonElement>('[role="radio"]:not(:disabled)'),
+                      )
+                      const current = radios.indexOf(document.activeElement as HTMLButtonElement)
+                      if (current < 0 || radios.length === 0) return
+                      event.preventDefault()
+                      const direction = event.key === 'ArrowRight' || event.key === 'ArrowDown' ? 1 : -1
+                      const next = radios[(current + direction + radios.length) % radios.length]
+                      next.focus()
+                      next.click()
+                    }}
+                  >
+                    {question.options.map((option) => {
+                      const selected = answer.selected.includes(option.label)
+                      const firstSelected = answer.selected[0]
+                      const firstOption = question.options[0]?.label
+                      const optionButton = (
+                        <Button
+                          type="button"
+                          size="sm"
+                          shape="pill"
+                          variant={selected ? 'secondary' : 'outline'}
+                          role={question.multiSelect ? undefined : 'radio'}
+                          aria-checked={question.multiSelect ? undefined : selected}
+                          aria-pressed={question.multiSelect ? selected : undefined}
+                          tabIndex={question.multiSelect
+                            ? undefined
+                            : selected || (firstSelected === undefined && option.label === firstOption)
+                              ? 0
+                              : -1}
+                          disabled={locked}
+                          onClick={() => {
+                            const selectedOptions = question.multiSelect
+                              ? selected
+                                ? answer.selected.filter((label) => label !== option.label)
+                                : [...answer.selected, option.label]
+                              : [option.label]
+                            changeAt(questionIndex, { ...answer, selected: selectedOptions })
+                          }}
+                        >
+                          {option.label}
+                        </Button>
+                      )
+
+                      return option.description ? (
+                        <Tooltip key={option.label}>
+                          <TooltipTrigger asChild>{optionButton}</TooltipTrigger>
+                          <TooltipContent>{option.description}</TooltipContent>
+                        </Tooltip>
+                      ) : (
+                        <React.Fragment key={option.label}>{optionButton}</React.Fragment>
+                      )
+                    })}
+                  </div>
+                  <Input
+                    value={answer.text ?? ''}
+                    onChange={(event) => changeAt(questionIndex, { ...answer, text: event.target.value })}
+                    placeholder="Outro (opcional)…"
+                    aria-label={`Outra resposta para: ${question.question}`}
+                    aria-invalid={invalid || undefined}
+                    aria-describedby={invalid ? errorId : undefined}
+                    disabled={locked}
+                  />
+                  {invalid && (
+                    <p id={errorId} className="text-sm text-destructive">
+                      Escolha uma opção ou escreva uma resposta.
+                    </p>
+                  )}
+                </fieldset>
+              )
+            })}
+          </div>
+        </TooltipProvider>
+        {!validCount && (
+          <p role="alert" className="mt-3 text-sm text-destructive">
+            Ask aceita de 1 a 4 perguntas.
+          </p>
+        )}
+        <div aria-live="polite" className="sr-only">
+          {submitted && !allAnswered ? 'Há perguntas sem resposta.' : ''}
+        </div>
+        <div className="mt-4 flex justify-end">
+          <Button type="submit" size="sm" busy={busy} disabled={disabled || !validCount}>
+            Responder
+          </Button>
+        </div>
+      </form>
+    </Card>
+  )
+}

package/src/ui/docs/content/ask.md

@@ -0,0 +1,31 @@
+Elicitação estruturada controlada baseada diretamente em `AskQuestion` e `AskAnswer`. O componente só apresenta e valida respostas; transporte, persistência e continuação do agente pertencem ao consumidor.
+
+```tsx preview
+const [answers, setAnswers] = React.useState([])
+
+render(
+  <Ask
+      questions={[
+        {
+          question: 'Qual ambiente devemos usar?',
+          header: 'Ambiente',
+          options: [
+            { label: 'Produção', description: 'Usa dados e serviços reais.' },
+            { label: 'Homologação', description: 'Usa o ambiente de validação.' },
+          ],
+        },
+        {
+          question: 'Quais verificações devo executar?',
+          header: 'Verificações',
+          multiSelect: true,
+          options: [{ label: 'Testes' }, { label: 'Typecheck' }, { label: 'Build' }],
+        },
+      ]}
+      answers={answers}
+      onChange={setAnswers}
+      onSubmit={(next) => console.log(next)}
+  />,
+)
+```
+
+Cada pergunta exige pelo menos uma opção válida selecionada **ou** texto livre não vazio. `busy` mostra o progresso no botão e trava os controles; `disabled` apenas trava a interação. A ordem de `answers` acompanha a ordem de `questions`, e o `header` de cada resposta é derivado de `question.header` (ou do próprio enunciado quando o header estiver vazio).

package/src/ui/docs/content/audit.md

@@ -31,6 +31,8 @@ interface AuditRecord {
   output?: unknown
   error?: ActionError
   severity: 'info' | 'warning' | 'error'
+  trace?: { requestId?: string; parentActionId?: string } // legado
+  traceContext?: TraceContext                              // vendor-neutral
   meta?: Record<string, unknown>
 }
 ```
@@ -48,6 +50,21 @@ const dev = consoleAudit()
 const prod = pgAudit({ pool, table: 'audit_log' })
 ```
 
+O default continua compatível com a tabela legada. Para persistir o contexto novo, primeiro
+adicione colunas próprias e depois habilite o opt-in — não reutilize as colunas legadas:
+
+```sql
+ALTER TABLE audit_log ADD COLUMN trace_id text;
+ALTER TABLE audit_log ADD COLUMN span_id text;
+```
+
+```ts
+const prod = pgAudit({ pool, traceContextColumns: true })
+```
+
+Rollouts com nomes existentes podem usar
+`traceContextColumns: { traceId: 'otel_trace_id', spanId: 'otel_span_id' }`.
+
 ## Dado sensível: o redator global
 
 Sem redator, os sinks persistem input e output **crus** — `user.create`/`setPassword`

package/src/ui/docs/content/observability.md

@@ -0,0 +1,71 @@
+---
+title: Observabilidade
+---
+
+# Observabilidade
+
+O core expõe uma porta vendor-neutral; o driver OpenTelemetry cria spans ativos para actions
+e reactions sem escolher backend, exporter ou Collector.
+
+## Driver OpenTelemetry
+
+Configure o SDK antes de criar o runtime. Exemplo com OTLP/HTTP apontando para um Collector:
+
+```ts
+import { NodeSDK } from '@opentelemetry/sdk-node'
+import { OTLPTraceExporter } from '@opentelemetry/exporter-trace-otlp-http'
+import { openTelemetryObservability } from '@softize/opus/observability/opentelemetry'
+import { createRuntime } from '@softize/opus/core'
+
+const sdk = new NodeSDK({
+  traceExporter: new OTLPTraceExporter({
+    url: 'http://otel-collector:4318/v1/traces',
+  }),
+})
+await sdk.start()
+
+const runtime = createRuntime({
+  observability: openTelemetryObservability({
+    shutdown: () => sdk.shutdown(),
+  }),
+})
+```
+
+O app é dono do `NodeSDK`, sampling, resource (`service.name`), exporter, autenticação e
+retry. A opção `shutdown` é explícita: sem ela, `runtime.dispose()` não desliga o provider
+global. Um `Tracer` também pode ser injetado para testes ou providers não globais.
+
+## Semântica
+
+- nomes de span: `opus.action <action>` e `opus.reaction <reaction>`;
+- parent vem de `ContextBase.trace` ou do evento recebido;
+- actions usam `ActionResult.ok` para status; reactions usam resolve/reject;
+- somente atributos allowlisted de baixa cardinalidade são anexados;
+- input, output, actor, tenant, request ID, error code/message e baggage não entram no span;
+- `TraceContext` devolve apenas `traceId`, `spanId`, `traceFlags` e `traceState`.
+
+## Fronteira HTTP W3C
+
+Os drivers Fastify e Node oferecem propagação explícita, desativada por default:
+
+```ts
+fastifyServer({ app, traceContext: 'w3c' })
+nodeServer({ traceContext: 'w3c' })
+```
+
+O opt-in extrai um `traceparent` v00 válido (e `tracestate` limitado) para
+`ContextBase.trace`. Depois da action, injeta na resposta o `traceparent` do contexto
+efetivo retornado pelo runtime. `baggage` nunca é lido nem copiado. Headers inválidos são
+ignorados; sem a opção, os drivers mantêm o comportamento anterior e não interpretam nem
+emitem contexto de trace.
+
+## Limites
+
+O driver OpenTelemetry não instrumenta HTTP automaticamente e não oferece backend APM.
+Use o opt-in dos drivers Fastify/Node acima ou forneça `ContextBase.trace` na instrumentação
+de outro transporte. A fronteira implementa somente `traceparent` v00 e uma validação
+defensiva limitada de `tracestate`; não é um propagator OTel genérico.
+Health do exporter/Collector só é reportado quando o app injeta `healthCheck`; o default
+confirma apenas que a API do driver está configurada.
+Sem um provider que produza spans válidos, o driver falha antes do callback e o runtime aplica
+a degradação lenient — executa a action uma vez, sem trace — em vez de propagar IDs inválidos.

package/src/ui/docs/content/queue.md

@@ -25,11 +25,14 @@ interface JobHandle<T = unknown> {
   data?: T
   error?: ActionError
   attempts: number
+  trace?: TraceContext
 }
 ```
 
-O core monta o `JobSpec` (action, input, ctx, retry/priority/timeout); o adapter persiste e
-processa.
+`runtime.execute()` valida a chamada, cria o `JobSpec` e inclui o trace efetivo, request ID e
+provenance original. O adapter persiste o envelope; o handle também expõe esse trace. No
+worker, `runtime.executeJob()` revalida o envelope e executa um span filho, preservando a
+cadeia request → enqueue → job sem aceitar baggage ou campos extras no carrier.
 
 ## Driver
 
@@ -52,10 +55,33 @@ const runtime = createRuntime({
 })
 ```
 
-A action declara `background: true` (+ retry/priority no contrato); chamá-la devolve um
+A action declara `background: { enabled: true }` (+ retry/priority no contrato); chamá-la devolve um
 `JobHandle` em vez do resultado, e o cliente pola `status(jobId)` (ou `subscribe`) até
 `done`/`failed`.
 
+## Worker BullMQ
+
+O app continua dono do `Worker` e da reidratação de autenticação. O processor chama
+`executeJob()` — nunca `execute()`, que criaria outro job:
+
+```ts
+new Worker('opus', async (job) => {
+  const spec = job.data as JobSpec
+  const ctx = await authContextForJob(spec.ctx)
+  const result = await runtime.executeJob(spec, ctx, {
+    report: (progress) => job.updateProgress(progress),
+  })
+  if (!result.ok) throw new Error(result.error.message)
+  return result.data
+}, { connection })
+```
+
+O runtime confirma que o actor reidratado corresponde a `spec.ctx.userId`; tenant, request,
+trace e provenance vêm do envelope. O driver mapeia `attempts`, backoff nativo e prioridade.
+Multiplicador exponencial diferente de 2 ou `maxMs` exige `backoffStrategy` custom do worker e
+é rejeitado pelo driver em vez de ser silenciosamente ignorado. `timeout` permanece no
+envelope para o worker aplicar, pois não é uma opção de execução do `Queue.add`.
+
 ## Limites (por enquanto)
 
 Driver hoje: `bullmq` (Redis). In-memory pra dev e outros backends (SQS, pg-boss…) entram

package/src/ui/docs/content/runtime.md

@@ -22,6 +22,7 @@ const runtime = createRuntime({
   data: kyselyData({ db }),            // fornece ctx.db
   auth: makeAuthAdapter(),             // resolve user/tenant/can
   audit: [pgAudit({ pool })],          // trilha de auditoria (N sinks)
+  observability: makeObservability(),  // span ativo + TraceContext vendor-neutral
   storage: fsStorage({ root }),        // fornece ctx.storage (experimental)
   config: { env, i18n: { defaultLocale: 'pt-BR' } },
 })
@@ -42,6 +43,7 @@ await runtime.start()
 | `auth` | `user`/`tenantId`/`can` do contexto | `jwtAuth` — `…/auth/jwt` · `betterAuthSession` — `…/auth/better-auth` |
 | `audit` | trilha por execução de action | `pgAudit` — `…/audit/pg` · `consoleAudit` — `…/audit/console` |
 | `log` | `ctx.log` estruturado | `pinoLogger` — `@softize/opus/log/pino` |
+| `observability` | span ativo + propagação de trace | porta no core; driver opt-in |
 | `eventBus` | `ctx.emit` + **reactions** | `mittEvents` — `@softize/opus/events/mitt` |
 | `queue` | jobs em background | `bullmqQueue` — `@softize/opus/queue/bullmq` |
 | `scheduler` | **schedules** (cron/intervalo) | `nodeCronScheduler` — `@softize/opus/scheduler/node-cron` |
@@ -60,7 +62,22 @@ Fora do runtime, mas parte do protocolo: o harness de teste (`runAction`/`testCo
 
 `user`/`tenantId`/`can` (auth) · `db` (data) · `log` (logger) · `emit` (eventBus) ·
 `storage` (storage) · `ai` (ai) · `provenance` (quem disparou: http, schedule,
-reaction…) · `meta`.
+reaction…) · `trace` (quando configurado) · `meta`.
+
+O core não depende de OpenTelemetry. O `ObservabilityAdapter` envolve actions e reactions
+com `runInSpan`; o `TraceContext` efetivo também segue para resultado, audit e eventos. Os
+envelopes de job recebem o trace da execução que enfileirou; `executeJob()` cria a execução
+filha no worker sem reenfileirar a action.
+Falha de instrumentação é lenient e nunca repete o handler.
+
+O core não extrai headers HTTP. Os drivers Fastify e Node podem fornecer
+`ContextBase.trace` com `traceContext: 'w3c'`; o opt-in é desativado por default. Outros
+transportes continuam responsáveis por sua fronteira. Em audit, o contexto novo usa
+`traceContext`; o campo `trace` legado continua disponível sem mudança.
+
+Para actions, o callback observável resolve com `ActionResult`: `resultKind: 'action-result'`
+indica que o driver deve inspecionar `result.ok`. Uma Promise resolvida com `ok:false` ainda
+representa span de erro. Reactions usam `resultKind: 'void'` e rejeitam em falha.
 
 ## Reactions e schedules
 

package/src/ui/docs/registry.tsx

@@ -56,6 +56,7 @@ import buttonGroupMd from './content/button-group.md?raw'
 import calendarMd from './content/calendar.md?raw'
 import cardMd from './content/card.md?raw'
 import carouselMd from './content/carousel.md?raw'
+import askMd from './content/ask.md?raw'
 import chatMd from './content/chat.md?raw'
 import checkboxMd from './content/checkbox.md?raw'
 import collapsibleMd from './content/collapsible.md?raw'
@@ -316,6 +317,7 @@ export const UI_SECTIONS: DocSection[] = [
       {
         label: 'IA',
         pages: [
+          { slug: 'ask', title: 'Ask', render: comp('Ask', 'ask', askMd) },
           { slug: 'chat', title: 'Chat', render: comp('Chat', 'chat', chatMd) },
           { slug: 'composer', title: 'Composer', render: comp('Composer', 'composer', composerMd) },
         ],

package/src/ui/meta.ts

@@ -11,6 +11,12 @@ import type { ComponentMeta } from './index.ts'
 
 /** Todos os metas, chaveados pelo nome canônico (kebab). Fonte única — zero duplicação. */
 export const componentMeta = {
+  'ask': {
+    name: 'ask',
+    ancestry: 'opus',
+    whenToUse:
+      'Elicitação estruturada controlada para 1–4 perguntas `AskQuestion`: opções single/multi em pills, texto livre opcional, validação e submit de `AskAnswer[]`. Não faz transporte, persistência nem integração automática com ChatEvent; o consumidor controla `answers`/`onChange` e conecta `onSubmit` ao canal apropriado.',
+  },
   'alert': {
     name: 'alert',
     ancestry: 'opus',

package/src/ui/react.tsx

@@ -19,6 +19,8 @@ export { Input } from './components/primitives/input.tsx'
 
 export { Chat } from './components/primitives/chat.tsx'
 export type { ChatProps, ChatMessage, ChatArtifact, ChatTranscriptItem } from './components/primitives/chat.tsx'
+export { Ask } from './components/primitives/ask.tsx'
+export type { AskProps } from './components/primitives/ask.tsx'
 export { Composer } from './components/primitives/composer.tsx'
 export type { ComposerProps } from './components/primitives/composer.tsx'
 export { Copyable } from './components/primitives/copyable.tsx'