SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsdym-agent-desktop-session

dym-agent-desktop-session

Agents & models

View repository

Updated 10-18 01:23

About this skill

dym-agent-desktop-session

When to use

  • A desktop operation turn needs to leave a receipt: /br qc, /fdk-poc, or any verdict must be arguable with logs rather than with the model's words.
  • Multiple agents running in parallel on the same macOS machine (exactly the Orca worktree context) — the mouse is a shared resource, and you need a lease and need to know which cursor belongs to which agent.
  • Running only a single read command → skip this skill, a session is overkill.

Steps

  1. Open a session once for the whole work turn (trace enabled):
$AD session start --name br-frame-07        # → data.session_id, data.next
export AGENT_DESKTOP_SESSION=run-1788964205617-6007-0

If you need pre/post images for each action to replay: session start --screenshots (artifacts: full) — sensitive, treat as screenshots, do not push into the repo.

  1. Do the work normally — every command in scope automatically writes JSONL, no need to --trace each command. The segment is at $AGENT_DESKTOP_HOME/sessions/<id>/trace/<pid>-<procTs>.jsonl.

  2. Read back the evidence:

$AD trace show --limit 200                  # JSON gọn cho agent đọc
$AD trace export --out ./scratchpad/run.html   # HTML một file cho người xem

Measure for real: each command generates command.start → business events (e.g. snapshot.saved with ref_count, snapshot_id) → command.end with duration_ms, ok. There is ts_ms and seq monotonic per process → the true order across multiple processes can be reconstructed.

  1. Close and clean up:
$AD session end $AGENT_DESKTOP_SESSION
$AD session gc --ended --older-than 86400
  1. Multiple agents in parallel (not verified by real runs this turn — per the tool's docs):
$AD session start --cursor --multi-agent    # một session dùng chung
AGENT_DESKTOP_AGENT_ID=frame-07 $AD click "@s..:e5"   # mỗi agent một ID ổn định
$AD cursor-overlay disable                  # tắt mọi cursor của session

The harness passes the same session ID to every subagent; each subagent declares its own AGENT_DESKTOP_AGENT_ID (or --agent-id, the flag beats the env). Three different IDs → three cursors with their own color/label. UI actions require an ID; observation/clipboard/administration do not. The lease serializes access to the shared OS cursor.

Rules

  • Session does not propagate by itself to the next process: session start only creates the manifest, you must pass AGENT_DESKTOP_SESSION or --session <id>yourself. Priority order: --session > env > no session.
  • --session <id> bare (without a manifest from session start) only selects the snapshot namespace, does NOT enable trace — existing callers do not get unexpected files.
  • Trace self-redacts sensitive fields (text, value, name, token, password, url, title, … → {"redacted": true}). But --screenshots redacts nothing — an image is an image.
  • --trace <path> overrides to a single file, for CI/one-off. --trace-strict only fails when writing the trace fails; by default post-action trace is best-effort → do not use "no trace line" as evidence that "no action occurred".
  • Ref is snapshot-scoped within a single namespace; lookup never crosses into another namespace. Agent A cannot use agent B's ref unless they share the same session and the same snapshot.
  • Before taking the trace as a receipt, status must show tracing: true and session_id the exact one in use.