logic-analyzer

name	logic-analyzer
description	Canonical host guidance for running the packaged logic-analyzer skill from @listenai/eaw-skill-logic-analyzer with the package-root request/result contract.

Help the host invoke the canonical logic-analyzer package through @listenai/eaw-skill-logic-analyzer, keep the packaged request shape intact, and preserve phase-aware diagnostics plus explicit cleanup behavior.

<canonical_source> This file and this package's README.md are the authoritative host-facing assets for logic-analyzer.

If you are working inside the monorepo, treat the package-owned documentation and exports as the source of truth. </canonical_source>

<when_to_use> Use this skill when the task is to analyze either a caller-supplied offline logic-capture artifact or a live DSLogic capture with the packaged one-shot entrypoint, then return structured waveform facts plus phase-aware failures. </when_to_use>

<required_surface> Import packaged skill runtime from @listenai/eaw-skill-logic-analyzer only, and import the connected resource-manager HTTP client from @listenai/eaw-resource-client when the host must capture and decode a connected protocol log.

Preferred skill-package exports:

• createGenericLogicAnalyzerSkill when the host will reuse a configured skill instance.
• runGenericLogicAnalyzer when a one-shot waveform or offline artifact call is simpler.
• createLogicAnalyzerSkill when the host needs explicit start/end session control before resource-manager capture/decode.
• listDsviewDecoders and inspectDsviewDecoder when the host needs package-root offline decoder metadata discovery.
• runDsviewDecoder when the host wants to call the offline artifact-only decode seam directly.
• Related request/result types from the same package-root surface when the host needs stronger typing.

Preferred resource-client export:

• HttpResourceManager for connected listDecoderCapabilities() and captureDecode() calls against resource-manager's /capture/decode route.

Do not deep-import internal modules from host code. Do not bypass resource-manager for connected live capture+decode. </required_surface>

<asset_lookup> If a host or installer needs the shipped guidance files, read this package's package.json metadata under listenai.skillAssets and resolve the returned paths inside the package root.

Current canonical keys:

• skillDescriptor -> ./SKILL.md
• readme -> ./README.md </asset_lookup>

<request_shape> Send one object in one of two modes:

• mode?: "artifact": existing offline callers provide session, artifact, and cleanup. They may also provide optional decode with decoderId, already-inspected decoder metadata, channelMappings, and optional decoderOptions.
• mode: "live": live callers provide session, capture, and cleanup.

The nested sections stay the same:

• session: the start-session request payload.
• artifact: the offline capture artifact payload.
• decode: optional offline protocol decode request; fixture-backed for this slice and additive to waveform analysis.
• capture: live capture timing inputs, currently requestedAt and optional timeoutMs.
• cleanup: currently requires endedAt for post-allocation cleanup attempts.

Keep the nested contracts intact. Do not flatten session, artifact, decode, capture, or cleanup fields into a new host-specific schema. </request_shape>

<connected_protocol_log_flow> For connected UART, I2C, SPI, or other protocol-log prompts, resource-manager owns connected capture+decode. Use HttpResourceManager and this sequence:

1. Check the packaged daemon health endpoint, normally http://127.0.0.1:7600/health unless the host explicitly configured another URL.
2. If the daemon is not healthy, check for the packaged eaw-resource-manager command and start it with eaw-resource-manager start --daemon --host 127.0.0.1 --port 7600 --json; if that command is missing or startup fails, fail closed with the install/startup diagnostic.
3. Create or receive a resource-manager client that points at the healthy packaged daemon.
4. Start a session through the package-root session surface, or use an existing typed session only if it is already allocated to this skill and still ready.
5. Call resourceManager.listDecoderCapabilities({ deviceId, requestedAt, timeoutMs }) before capture. Fail closed if resource-manager is unavailable, the response is malformed, the result is ok: false, or the requested decoder such as 1:uart is absent.
6. Call resourceManager.captureDecode({ session, requestedAt, timeoutMs, captureTuning, decode }). This is the connected protocol-log path and maps to /capture/decode.
7. Branch on ok; when false, preserve diagnostics.phase, kind, message, session, providerKind, backendKind, artifactSummary, decode, and nested diagnostics instead of replacing them with prose.
8. Write host-visible decoded output only from the ok: true branch, preferring decode.raw.text / decode.raw.bytes and falling back to decode.rows or decode.annotations when raw payloads are unavailable.

Never tell Codex, Claude, or a human operator to run dsview-cli capture for a connected protocol-log workflow. Never search parent directories for a source checkout, never run ../listenai_agent_skills, packages/resource-manager/dist/cli.js, src/cli.ts, or pnpm --filter @listenai/eaw-resource-manager as a host fallback. Direct package decode remains offline artifact-only: runDsviewDecoder and dsview-cli decode run may be used only after a caller supplies an existing artifact. </connected_protocol_log_flow>

<execution_flow> For packaged waveform/offline artifact requests:

1. Validate the top-level packaged request.
2. Start a logic-analyzer session through the existing session seam.
3. Either load the supplied offline artifact or run live waveform capture through the shared manager/client seam.
4. Analyze the normalized capture through the waveform-analyzer seam.
5. If offline decode is present, validate it against inspected decoder metadata and run the injected dsview-cli decode run seam.
6. If a failure happens after allocation, surface the cleanup attempt and cleanup result instead of hiding it.

For connected protocol-log capture+decode requests, prefer the connected_protocol_log_flow: HttpResourceManager.listDecoderCapabilities() followed by HttpResourceManager.captureDecode(). Protocol decode is not a replacement for resource-manager authority. Resource-manager remains responsible for hardware allocation, ready-session validation, live capture, and connected decoder execution; the package-owned direct decode seam consumes caller-provided offline artifacts and adds protocol facts without replacing waveform analysis. </execution_flow>

<result_handling> Branch first on ok and then on phase.

Successful result:

• ok: true
• phase: "completed"
• Includes the allocated session, normalized capture metadata, waveform analysis output, and captureSession details for live runs.
• Includes decode only for offline requests that supplied optional protocol decode and completed dsview-cli decode run successfully; this payload is additive and does not replace analysis.

After a successful packaged run, keep using the package-root surface for cleanup: the device stays allocated until the host explicitly calls endSession(...) with the returned session details.

Failure result:

• phase: "request-validation" exposes top-level request issues before allocation.
• phase: "start-session" preserves the nested session-start failure payload.
• phase: "live-capture" preserves live request validation, runtime timeout/failure, or malformed live artifact details plus the visible cleanup outcome.
• phase: "load-capture" preserves the nested loader failure payload and the visible cleanup outcome.
• phase: "decode-validation" preserves decode validation issues, artifact summary, capture, waveform analysis, and the post-allocation cleanup outcome.
• phase: "decode-run" preserves decode reason/code/message/detail, command/args/stdout/stderr/exit code/signal/native code, artifact summary, temp cleanup, capture, waveform analysis, and the post-allocation cleanup outcome.

Connected captureDecode() failure result:

• ok: false with reason: "capture-decode-failed".
• diagnostics.phase identifies whether failure happened during validation, capture, decode validation, or decode runtime.
• Preserve kind, message, session, providerKind, backendKind, backendVersion, artifactSummary, decode, stream summaries, and inventory diagnostics for agent inspection.

Treat nested payloads as authoritative diagnostics. Do not replace them with a new summarized reason string. If the HTTP transport returns malformed payloads, let the transport/parser error surface instead of fabricating a typed packaged runner failure. </result_handling>

<host_support> Use the package README's DSLogic support matrix as the operator-facing truth.

Support summary:

• macOS + dsview-cli: live-proven in M010 when backend readiness is ready, the classic DSLogic Plus path is ready, and the packaged acceptance seam still passes.
• Linux: readiness-modeled; treat backend-missing-runtime, backend-runtime-timeout, backend-runtime-malformed-response, backend-unsupported-os, device-unsupported-variant, and device-runtime-malformed-response as truthful dsview-cli operator diagnostics instead of implied live support.
• Windows: readiness-modeled; treat backend-missing-runtime, backend-runtime-timeout, backend-runtime-malformed-response, backend-unsupported-os, device-unsupported-variant, and device-runtime-malformed-response as truthful dsview-cli operator diagnostics instead of implied live support.

Keep the shared contract vocabulary intact:

• device readiness: ready, degraded, unsupported
• backend readiness: ready, degraded, missing, unsupported </host_support>

<host_instructions>

• Read this package's README.md for host-neutral examples, Codex and Claude install destinations, adaptation notes, and the current verification commands.
• For Codex installation, prefer registry one-shot execution: npm exec --package @listenai/eaw-skill-logic-analyzer -- listenai-logic-analyzer-install-codex <codex-skills-directory>, pnpm dlx --package @listenai/eaw-skill-logic-analyzer listenai-logic-analyzer-install-codex <codex-skills-directory>, or yarn dlx @listenai/eaw-skill-logic-analyzer listenai-logic-analyzer-install-codex <codex-skills-directory>. Target either ~/.codex/skills or .codex/skills; the installed skill lives at logic-analyzer/ under that directory and contains this package-owned SKILL.md plus README.md.
• For Claude Code installation, prefer registry one-shot execution: npm exec --package @listenai/eaw-skill-logic-analyzer -- listenai-logic-analyzer-install-claude <claude-skills-directory>, pnpm dlx --package @listenai/eaw-skill-logic-analyzer listenai-logic-analyzer-install-claude <claude-skills-directory>, or yarn dlx @listenai/eaw-skill-logic-analyzer listenai-logic-analyzer-install-claude <claude-skills-directory>. Target either ~/.claude/skills or .claude/skills; the installed skill lives at logic-analyzer/ under that directory and contains this package-owned SKILL.md plus README.md.
• Keep repo-local callers on the package-owned import path so docs and runtime entrypoints stay canonical.
• For connected protocol-log prompts, use HttpResourceManager, require listDecoderCapabilities() to expose the requested decoder such as 1:uart, then call captureDecode(); fail closed when the packaged daemon, capability lookup, session allocation, or the typed capture/decode result is unavailable.
• Bootstrap connected protocol-log work only through the packaged eaw-resource-manager command when the daemon is not already healthy; never discover or execute a sibling source checkout as a fallback.
• Keep optional package-owned protocol decode offline and additive for this contract: hosts pass inspected decoder metadata and an injected command runner, then continue returning waveform analysis alongside any decode report.
• Keep resource-manager as the live capture authority; do not route live allocation, probe readiness, connected capture, or connected decode through direct dsview-cli capture guidance.
• Maintainer-only source verification belongs inside this repository after cloning it intentionally; do not run monorepo verification commands from an installed host project.
• Maintainer-only source verification belongs inside an intentional source checkout; installed host projects must not run repository scripts or search for a sibling monorepo.
• Keep user-visible reporting aligned with the returned structured payloads.
• Preserve cleanup diagnostics when reporting post-allocation failures.
• After a successful packaged run, explicitly call endSession(...) through the package-root surface when the host wants to return the device to free. </host_instructions>

<success_criteria> The host uses the package-root exports from @listenai/eaw-skill-logic-analyzer for packaged waveform/offline artifact work, uses HttpResourceManager.listDecoderCapabilities() and HttpResourceManager.captureDecode() for connected protocol-log capture+decode, passes nested contracts unchanged, returns either successful decoded rows/annotations or the phase-aware failure object with cleanup and backend visibility intact, and explicitly ends successful sessions when the device should be released. </success_criteria>