Tracker connectors

A tracker connector is a connector with a tracker block. The factory keeps a tracker item and its task in step both ways: outgoing status, comments and links are effects held at the run-end gate; incoming status and content changes arrive through intake.

This page uses the hidden kusaw connector demo-files server. Point mcp.command at kusaw connector demo-files --dir <folder>. Each markdown file is one item; front matter may include status. The server exposes list_items, get_item, update_status, add_comment and add_link.

MappingCopy Anchor Link

connectors:
  demo-tracker:
    mcp:
      command: ["kusaw", "connector", "demo-files", "--dir", "items"]
    intake:
      tool: list_items
      item:
        id: id
        title: title
        body: description
        type: kind
        labels: labels
        url: url
        updated: updated_at
        status: status
      mode: hold
    context:
      item: { tool: get_item, args: { id: "{{item.id}}" } }
    write_back:
      set_status: { tool: update_status }
      comment: { tool: add_comment }
      link: { tool: add_link }
    tracker:
      statuses:
        "To do": todo
        "In progress": in_progress
        "In review": in_review
        "Done": done
        "Won't do": cancelled
      out:
        run_started: "In progress"
        delivered: "In review"
      comment_on: [delivered, needs_attention, failed]
      link_on: [delivered]

intake.item.status is one dotted path, or a list of paths whose non-empty values join with : (GitHub Issues uses [state, state_reason]). Factory meanings are todo, in_progress, in_review, done, cancelled. Anything else is other: shown, never acted on.

Omitted out, comment_on and link_on moments write nothing. write_back.<name>.fixed pins arguments the core always sends (for example {method: update} on a tool that can also create). The factory never creates tracker items.

OutgoingCopy Anchor Link

At run_started, delivered, run_done, needs_attention, failed and cancelled, the core proposes <connector>.set_status, .comment and .link effects with step id tracker-sync, always scope: outside. They wait for kusaw effects apply <run-id>. Comment text uses the fixed templates (or tracker.comment_templates) and ends with factory-run: <run-id>.

When the tracker has no link tool, link_on moments embed the URL in the comment instead.

IncomingCopy Anchor Link

Each poll classifies a diff as status, content, or both. content_sha256 covers title, body, type and labels only. Echoes of a factory status write from the last 24 hours are stored as echo and never held. kusaw connector changes lists held changes; accept and ignore apply to that item's held changes as well as first-seen items.

A running run is never stopped by an incoming change. If the item is closed while the run is going, the run ends needs_attention / tracker_item_closed.

ConflictsCopy Anchor Link

Before sending set_status, the broker re-reads context.item. If the tracker status is no longer base_status and is not the value being written, the effect fails and is not sent. The tracker wins. kusaw effects shows the conflict; serve logs one warn line; event connector.sync_skipped is appended.

GitHub IssuesCopy Anchor Link

See examples/connectors/github-issues/kusaw.yaml. It uses GitHub's official MCP server (github/github-mcp-server) with the issues toolset and GITHUB_PERSONAL_ACCESS_TOKEN as a secret. out is empty by default (a merged pull request that names the issue closes it in GitHub).