# A2A Agent Connection Skill

Use this when a Ysee Web page gives you an Agent-readable onboarding prompt.
Your job is to connect the named local Agent to Ysee through Agent Unit /
runtime-direct.

## Fixed Architecture

- Ordinary user path: Agent Unit / runtime-direct.
- Coding-agent and other non-interactive connect/recovery commands use
  `--detach`, so Agent Unit continues in the background after the command
  returns. The hidden interactive connect fallback stays in the foreground.
- Host / Device / Connector / DCK / Agent Host / Host-first binding are
  deprecated and must not be used as the current path.
- Runtime pulls `task_runs`; Adapter calls the local provider. Do not invent a
  second execution path.

## Connection Code Rules

The Web prompt may contain a one-time connection code. Treat it as a secret.

Allowed:

- Read it from the Web prompt.
- Pass it through stdin to Agent Unit.
- Paste it once into Agent Unit hidden interactive input.
- Use `--code-file <path>` only as a fallback; delete the temporary file after
  use.

Forbidden:

- Do not pass it as `connect <code>` except for deprecated compatibility.
- Do not use `echo <code>` or `printf <code>`.
- Do not print, log, summarize, or repeat the code.
- Do not write it to repo tracked files, long-term local files, status, doctor,
  logs, or chat.

## Main Command

POSIX heredoc:

```bash
npx -y @ysee/agent-unit@alpha connect --api-base <api_base> --code-stdin --detach <<'YSEE_CODE'
<CODE>
YSEE_CODE
```

PowerShell equivalent:

```powershell
@'
<CODE>
'@ | npx -y @ysee/agent-unit@alpha connect --api-base <api_base> --code-stdin --detach
```

Interactive terminal fallback:

```bash
npx -y @ysee/agent-unit@alpha connect --api-base <api_base>
```

Paste the code only at the hidden prompt. Input should not echo.
This interactive fallback runs in the foreground; keep its terminal open.

After a detached connect/start, check Agent Unit with
`npx -y @ysee/agent-unit@alpha status --agent-id <agent_id>` and stop it with
`npx -y @ysee/agent-unit@alpha stop --agent-id <agent_id>`.

`--code-file <path>` is a fallback when stdin/interactive input is unavailable,
not the main path.

## Existing Profile First

If the Agent already has a local profile, do not consume a new code.

```bash
npx -y @ysee/agent-unit@alpha status --agent-id <agent_id>
npx -y @ysee/agent-unit@alpha doctor --agent-id <agent_id>
npx -y @ysee/agent-unit@alpha start --agent-id <agent_id> --api-base <api_base> --detach
```

If the profile or lock is stale:

```bash
npx -y @ysee/agent-unit@alpha repair --agent-id <agent_id>
npx -y @ysee/agent-unit@alpha stop --agent-id <agent_id>
```

If the same Agent exists under multiple API bases, pass `--api-base <api_base>`
or `--profile profile_id` for start/stop/repair.

Do not run `killall node` or `killall agent-unit`.
Live locks fail closed by default. Use `--takeover` only after confirming the
existing Unit is safe to stop and ownership can be verified.

## Provider Login / Env

Prefer the provider login/API configuration already available in the current
interactive terminal. Claude, Codex, Hermes, and custom providers are local
provider choices; do not silently fall back to Claude.

Agent Unit v1 passes the full terminal env to the local provider child process
for provider CLI, proxy, relay, and custom variable compatibility. You must
never dump env values, read `.env*`, write API key values to `adapter.json`, or
report them to Ysee/Web/chat. Doctor/status may show only whether selected env
variable names are present.

## What To Report

Report only:

- Result: connected / need new code / still unavailable.
- Reason: one short sentence.
- Next step: one short sentence.

Never include connection code, runtime_token, JWT, Authorization, session_key,
host_session_ref, API key, local profile contents, raw logs, or local filesystem
paths.

## Failure Hints

- Code expired or already used: ask the user to generate a fresh code.
- Old process or stale lock: run status/doctor, then stop or repair; use
  `--takeover` only after confirming it is safe.
- First-time connect + old live lock after attach: the code may be consumed;
  stop the old Unit, generate a fresh Web code, and connect again.
- Damaged profile: doctor, then repair.
- Provider not logged in: ask the user to log in from the usual terminal and
  restart Agent Unit.
- Invalid model/provider config: edit `adapter.json` without storing secrets.
- Network/npm failure: report the specific non-secret error class.