composer-debug

Evaluate expressions and invoke operations in a live Composer app via the loopback debug port.

518|49|Updated Apr 7, 2021
One-click install
npx skills add https://github.com/dxos/dxos --skill composer-debug
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: composer-debug
Source: https://github.com/dxos/dxos/tree/main/.agents/skills/composer-debug
Command: npx skills add https://github.com/dxos/dxos --skill composer-debug

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Debugging a running Composer app normally means asking the user to paste console output or screenshots back and forth. This Skill lets the agent evaluate JavaScript directly inside the user's live Composer tab through a user-activated loopback debug port, so a wrong probe costs a retry instead of a round trip.

Core Features & Use Cases

  • Live expression evaluation: Run async snippets against the dxos devtools hook and composer app-framework namespace, with JSON-serialized results returned to the agent.
  • Plugin and operation introspection: List enabled plugins, enumerate operations, and invoke operations by DXN key to inspect or reshape the running app.
  • UI state snapshots: Capture the live layout, attention, open planks, and available actions as one JSON document to drive a snapshot-invoke-snapshot debugging loop.
  • Use Case: A user's Composer profile boots but a space query returns nothing. Ask the user to enable the debug port in Settings, connect with the session id, then probe space state, plugin activation, and diagnostics directly instead of guessing.

Quick Start

Ask the user to open Settings, enable the Agent debug port, and share the session id so you can evaluate a read-only status snippet against their live Composer client.

Frequently Asked Questions about composer-debug

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I debug a live Composer app from an AI agent?

Ask the user to enable the Agent debug port in Settings under Debug and copy the session id. Then run the composer-recovery.js script with that id and a JavaScript snippet; the script delivers the snippet to the page and prints the JSON result.

How do I list plugins and operations in a running Composer instance?

Call composer.plugins() for id, enabled, and active state, and composer.operations() for invocable operation keys with input and output fields. Both run as snippets through the debug port once React has mounted the composer namespace.

What is the difference between composer-debug and composer-forensics?

composer-debug targets the running app: the live client, plugins, and operations. composer-forensics covers the safe-mode /recovery.html port and storage-level work like export, import, SQLite, and Automerge compaction. Both share the same wire protocol and script.

Why did the Composer debug port stop working?

A page reload stops the port because a fresh session id is minted per activation and nothing is persisted. Ask the user for a new session id rather than retrying the old one, and raise COMPOSER_RECOVERY_CONNECT_TIMEOUT if the tab polls slowly.

Can the agent invoke mutating operations through the debug port?

Only with explicit user confirmation for that specific action. The skill is read-only by default, and operations like dxos.reset(), compactDocuments, or imports must never run without consent. Database-backed operations also need a spaceId passed through the operation invoker.

Why does composer.invoke fail with Service not available for Database?

Operations declaring Database.Service need a spaceId that composer.invoke does not pass. Resolve the operation definition through the plugin manager's capabilities and call the operation invoker directly with an explicit spaceId option.