owner-agent-consult

Files (4)

• SKILL.md
• manifest.json
• consult.py · scripts/
• consult_policy.py · scripts/

SKILL.md (first lines)

# Owner-agent consult

One owner often runs several agents (one per machine, one per project). When your owner asks
you something whose answer lives with a sibling agent, ask the sibling instead of guessing.

Messages are ordinary chat. The ask is the question, starting with the asked agent's exact
mxid; the answer is that agent's reply in the thread. The consult id, the thread root and the
ask's event live only in the asking agent's state files, so any agent can answer, including
one that does not run this skill.

## Out of scope

- **No onward consults.** An asked agent answers from what it holds. It does not ask a third
  agent, and there are no chains, follow-ups or second asks.
- **No recovery.** When the outcome of a post is unclear (a timeout, no event id, output that is
  not JSON), the ask or answer stays **unconfirmed**. It is never looked for in the room and never
  posted again. Tell the owner you could not confirm the ask; the owner asks again with a new
  message, which is a new task. A crash mid-consult likewise leaves it pending.
- **An answer is delivered at most once.** `match --final` returns the answer once and never
  again. A crash between the close and the relay is reported, not retried: `pending` lists the
  consult as `closed_unrelayed`, and you tell the owner that the answer may not have been
  delivered (at least once: a second crash may repeat the notice). The owner's next message is a
  new task.
- **AG2 Space origins only.** `ask` accepts only an owner task with `source: ag2space`, whose
  conversation the relay can reach with `[channel:]` and `[thread:]`. A task from another source
  is refused; answer it without consulting.
- **Exact mxid only.** An ask is recognised only when its plain body starts with the asked
  agent's exact mxid, followed by the end of the body or one separator (` — `, `: `, a space or a
  newline). A longer mxid that starts with it is another agent. A client pill that shows only a
  display name is not recognised.

## When to use it: all of these, or do not

1. **It starts from your owner's task.** `ask --task-id <owner task>` takes the task's id, never
   a path or text. The task must be live in this workspace's inbox, carry a verified envelope,
   `access_tier: owner` on every tier line, no collaborator flag and no result. A task from the
   consult room itself counts only when the owner wrote it.
2. **The answer genuinely depends on another agent.** "It owns that host and I do not" is a
   reason; "it might know more" is not.
3. **Whom to ask comes from `collaboration-intelligence`**, never from recall. This skill only
   checks that the agent is one of your owner's agents in the consult room.

Not for coordination, hand-offs, review requests, anything another person should see, or fanning
one question out to several agents.

## Configure (manifest `config`, `CLI > env > manifest`)

| key | default | meaning |
| --- | --- | --- |
| `OWNER_AGENT_CONSULT_ROOM` | empty | the consult room id. Unset: inert, and says so. |
| `OWNER_AGENT_CONSULT_ROOM_CLI` | empty | absolute path of the room transport CLI (below). Unset: inert. |
| `OWNER_AGENT_CONSULT_NUDGE_AFTER_S` | `600` | when an unanswered consult is due a note to the owner (60–86400). |
| `OWNER_AGENT_CONSULT_MAX_DURATION_S` | `1800` | the answer window: a reply counts only if posted within this long after the ask, by server time (60–86400). |
| `OWNER_AGENT_CONSULT_EXPIRE_AFTER_S` | `604800` | after this, a new match is refused, and a nudged consult whose task is done is hidden from `pending` (3600–7776000). No record is deleted. |
| `OWNER_AGENT_CONSULT_ENABLED` | `1` | `0`/`false`/`off` makes it inert. |

On a desktop install prefer env overrides: the engine tree, manifest included, is replaced on
update. In AG2 Space, give the owner's agents **Owner** access in the consult room (or Team with
Agent Native **Collaborator access**); with plain Team access the asks and answers reach each
agent on the read-only path, which cannot run `consult.py`.

## Ask

```bash
python3 skills/owner-agent-consult/scripts/consult.py roster --agent "<your-mxid>"
python3 skills/owner-agent-consult/scripts/consult.py ask --agent "<your-mxid>" \
  --agent-to "<mxid from roster>" --question-file <file> --task-id <owner task id>
```

The question file is the question in plain words. `ask` posts it as a new top-level message
that roots the consult thread, records the consult under
`<workspace>/state/owner-agent-consult/pending/<cid>.json`, and returns at once. It never reads
the room. When the owner sets a bound ("give it five minutes"), pass `--max-duration`; the
smaller of it and the config applies.

- `{"ok": false, "inert": true}`: not configured. Answer without consulting.
- `{"asked": true, "cid", "ask_event", "root"}`: finish the owner's task now. Tell the owner you
  asked that agent and will come back with its answer.
- `{"asked": true, "unconfirmed": true, "warning"}`: tell the owner you could not confirm the
  ask; they can ask again with a new message.
- `{"asked": false, "reason"}`: refused. Tell the owner in one line why, then answer from what
  you hold. A second ask from the same task is always refused: one ask per task.

## Answer (when an ask arrives at you)

It arrives as a task from the consult room. Any agent may just reply in the thread. An agent
running this skill should use `answer`, which posts at most once:

```bash
python3 skills/owner-agent-consult/scripts/consult.py answer --agent "<your-mxid>" \
  --task-id <the ask's task id> --body-file <answer file>
```

It refuses unless the ask's task is live, verified, from the consult room and has no result, and
the ask is a thread root, from another of the owner's agents, starting with your exact mxid.
It replies in the ask's thread, cites the ask and mentions the asker, so the asker gets a task.
A retry reports the recorded post without posting again; an unconfirmed answer is refused, not
posted again.

## Match the answer

The answer is the asked agent's first message in the consult thread, or replying to the ask,
inside the answer window. It may arrive as a task (when it mentions you), or only show in
`pending` as `answer_waiting`. Two steps:

1. **Look:** `match --task-id <that task>` or `match --event-id <event>` returns
   `candidate: true` with `reply_text`. It changes nothing.
2. **Judge:** run it again with `--final` (the answer: binds the message and closes the consult)
   or `--not-final` (progress, such as "On it"; the agent's next message becomes the candidate).
   The judgement is yours; no text rule decides.

A message can belong only to the consult whose thread it is in or whose ask it cites; a message
whose thread and reply point at different consults belongs to neither: it binds nowhere and does
not hold up either consult. A later message is refused
until the earlier ones are judged. Each message is bound once (`bound/<event>.json`, never
deleted) and its recorded judgement wins: the opposite flag is refused (`conflict: true`). A
message bound as the answer holds everything needed to close, so `--final --event-id` finishes a
close that failed, even when the message has left the room read or the consult has expired;
`pending` shows that message under `answer_waiting` with `bound: "answer"`, and keeps the consult

From sonichi/sutando, MIT.

More from sonichi/sutando