Connect and coordinate

Record an update for the user. Reuse a stable ref and keep summaries short and factual. A ref names one occurrence: a new reply, reschedule or comment gets its own ref. attention: notify. intent: claim work. done: finish work. note: share context. Do not notify on duplicate or seen. Do not act on held or seen. key_conflict: the key was used for a different ref or payload; nothing was written. Use a new key. seen and held store nothing. seen: the ref is done or acked. On an acked ref, attention at high or urgent above every stored attention urgency re-opens it and returns updated. held: another agent holds a live intent on the ref; held_by and until name the holder and lease end. Only intent returns held. similar (new posts only) lists open refs whose summaries share most terms with this one. If similar contains the same item, call link. Entries expire 7 days after the last post. Intent expires at ttl or on done; a re-post without ttl keeps the current lease length. Ref conventions (user patterns replace starters for the same source): calendar | calendar:{calendar_id}/{event_id} | calendar:work/event-123 chat | chat:{thread_id} | chat:standup-2026-11-01 email | email:{message_id_header} | email:CAF1x2y3@mail.gmail.com file | file:{canonical_uri} | file:drive/document-123 task | task:{system}/{task_id} | task:github/issue-123 web | web:{canonical_url} | web:https://example.com/article

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "\\S"
    },
    "kind": {
      "type": "string",
      "enum": [
        "attention",
        "intent",
        "done",
        "note"
      ]
    },
    "summary": {
      "type": "string",
      "minLength": 1,
      "maxLength": 120
    },
    "urgency": {
      "type": "string",
      "enum": [
        "low",
        "normal",
        "high",
        "urgent"
      ]
    },
    "ttl": {
      "type": "integer",
      "minimum": 1,
      "maximum": 86400
    },
    "key": {
      "type": "string",
      "minLength": 1,
      "maxLength": 128,
      "description": "Idempotency key, e.g. derived from the task. A retry with the same key, ref and payload returns the first result; the same key with a different ref or payload returns key_conflict and writes nothing."
    }
  },
  "required": [
    "ref",
    "kind",
    "summary"
  ]
}

Read current entries before acting. Omit ref to list entries on open refs (not acked, not done); filter with kind. kind=done instead lists done entries on completed refs. With a ref, every unexpired entry on that ref returns. Pass wait (1 to 60 seconds) to block until a matching entry is new or changes; only those entries return, or none when the wait elapses. Pass since (the cursor of an earlier read) to poll: every matching entry returns with replay true when it last changed at or before the cursor, false when new, plus a fresh cursor and an advisory next_poll_ms. For a briefing, read kind=attention: summarize urgent entries first, group by ref, name agents, then ack after delivery.

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "\\S"
    },
    "kind": {
      "type": "string",
      "enum": [
        "attention",
        "intent",
        "done",
        "note"
      ]
    },
    "wait": {
      "type": "integer",
      "minimum": 1,
      "maximum": 60
    },
    "since": {
      "type": "integer",
      "minimum": 0,
      "maximum": 4102444800
    }
  }
}

Confirm delivery to the user. Returns each ref as given, under acked or unknown (no live item). Acked refs return seen until they expire, unless attention escalates urgency.

{
  "type": "object",
  "properties": {
    "refs": {
      "type": "array",
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 256,
        "pattern": "\\S"
      },
      "minItems": 1,
      "maxItems": 100
    }
  },
  "required": [
    "refs"
  ]
}

Merge refs for the same item. The ref whose item was created first stays canonical; ties go to ref. Errors: self_link when ref and to are the same ref; unknown_refs when neither ref has live entries. One side may be unposted: it becomes an alias. Aliases last as long as the canonical item: when it expires and is gc'd, its aliases go with it.

{
  "type": "object",
  "properties": {
    "ref": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "\\S"
    },
    "to": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "\\S"
    }
  },
  "required": [
    "ref",
    "to"
  ]
}

Improve a ref convention with a pattern and matching example. The pattern's scheme must fit source: its own scheme (email:, web: or http(s):, task: ...) or a vendor scheme no source owns (gmail:, gh:), never another source's. Result: matches counts live refs that already follow the pattern; it is informational and does not adopt. vendors lists vendors whose posts counted toward adoption. Adoption needs two vendors: a post on a matching ref that already holds an entry from an agent of another vendor records both, and two vendors activate the convention. Unadopted proposals expire after 7 days unused. Active conventions stay until the owner reverts them with onref-admin revert <id> (onref-admin conventions lists them); proposing an expired pattern again starts it over.

{
  "type": "object",
  "properties": {
    "source": {
      "type": "string",
      "enum": [
        "email",
        "calendar",
        "web",
        "payment",
        "task",
        "file",
        "chat",
        "other"
      ]
    },
    "pattern": {
      "type": "string",
      "pattern": "^[a-z0-9+.-]+:[^\\s]{1,120}$"
    },
    "example": {
      "type": "string",
      "minLength": 1,
      "maxLength": 256,
      "pattern": "\\S"
    }
  },
  "required": [
    "source",
    "pattern",
    "example"
  ]
}