소켓 API

Herdr는 실행 중인 세션을 검사하거나 제어해야 하는 스크립트 및 에이전트를 위한 로컬 소켓 API를 노출합니다.

자동화는 우선 CLI 명령어로 시작하는 것이 좋습니다. 요청과 응답을 직접 제어하거나 이벤트를 지속적으로 구독해야 할 때 소켓 API를 사용하세요.

레이어는 동일한 제어 표면을 공유합니다.

설치된 CLI는 해당 Herdr 바이너리와 함께 번들로 제공되는 소켓 프로토콜 스키마를 출력할 수 있습니다.

herdr api schema
herdr api schema --json
herdr api schema --output herdr-api.schema.json

일반 herdr api schema은 짧은 요약을 출력합니다. --json은 도구에 대한 전체 JSON 스키마 문서를 출력하고 --output PATH는 해당 문서를 파일에 씁니다. 스키마는 원시 요청, 성공 응답, 오류 응답, 생성된 이벤트 및 구독 이벤트를 다룹니다.

소켓 API는 다음을 수행할 수 있습니다.

• 작업 공간 생성, 나열, 집중, 이름 바꾸기 및 닫기
• 탭 생성, 나열, 집중, 이름 바꾸기 및 닫기
• 나열, 검사, 분할, 교환, 초점, 크기 조정, 이름 바꾸기, 읽기, 닫기 및 패널에 입력 보내기
• CLI 도우미를 통해 에이전트 나열, 검사, 읽기, 프롬프트, 대기, 이름 바꾸기, 집중, 시작 및 연결
• 훅 및 플러그인에서 사용자 정의 에이전트 상태 보고
• 이벤트를 구독하고 출력 또는 상태 변경을 기다립니다.
• 내장 통합 설치 및 제거
• 서버를 중지하고 구성을 다시 로드하세요.

작업 공간을 만듭니다.

herdr workspace create --cwd ~/project --label api

탭을 만듭니다.

herdr tab create --label logs

패널을 분할하고 명령을 실행합니다.

herdr pane split w1:p1 --direction right
herdr pane run w1:p2 "npm test"

패널을 검사하고 재정렬합니다.

herdr pane layout --current
herdr pane neighbor --direction right --current
herdr pane resize --direction right --amount 0.1 --current
herdr pane swap --direction right --current
herdr pane zoom --on --current
herdr pane split w1:p1 --direction right --ratio 0.333

에이전트을 기다립니다.

herdr agent wait w1:p1 --until done

창 출력 읽기:

herdr pane read w1:p2 --source recent --lines 50

원시 소켓 메서드 이름은 점 표기법을 사용합니다.

agent.wait은(는) 서버 소유이며 이벤트 중심입니다. 교체가 대기를 만족시킬 수 없도록 해결된 패널 점유자를 고정합니다. agent.prompt은 until 및 timeout_ms와 함께 선택적 wait 개체를 허용합니다. 그러면 프롬프트가 제출되고 하나의 요청으로 대기가 시작되므로 별도의 호출 간의 경합이 방지됩니다. 해결된 에이전트가 이미 blocked인 경우 agent.prompt은 입력을 보내거나 대기를 시작하지 않고 agent_blocked을 반환합니다.

workspace.move_block은 주문된 workspace_ids을 before_workspace_id 앞으로 원자적으로 이동합니다. 블록을 끝으로 이동하려면 앵커를 생략하세요. ID는 고유해야 하며 앵커는 블록의 일부가 될 수 없습니다. 응답에는 신뢰할 수 있는 정렬된 작업 공간 목록이 포함되어 있습니다.

session.snapshot은 자체 로컬 런타임 캐시를 유지하는 클라이언트에 대한 일회성 부트스트랩 스냅샷을 반환합니다. 응답에는 버전/프로토콜 메타데이터, 집중된 작업 공간/탭/창 ID, 작업 공간 레코드, 탭 레코드, 패널 레코드, 탭 레이아웃 스냅샷 및 에이전트 레코드가 포함됩니다. 구독이 아닙니다. 캐시 부트스트랩 및 복구를 위해 먼저 구독한 다음 아래 이벤트 구독에 설명된 대로 권한 있는 읽기를 통해 조정합니다. 이벤트는 캐시된 상태를 무효화합니다. 스냅샷을 통해 무조건 재생할 수는 없습니다. 다시 연결한 후 또는 로컬 캐시가 오래되었을 때 session.snapshot을 다시 호출하세요. 첨부된 작업 트리 출처는 작업 공간 레코드에 포함됩니다. 전체 저장소 작업 트리 검색은 worktree.list로 유지됩니다.

CLI에서 herdr api snapshot은 간단한 부트스트랩 명령을 원하는 클라이언트 및 에이전트에 대해 실시간 session.snapshot 응답을 JSON으로 출력합니다.

창 제어 방법은 w1:p1과 같은 공개 패널 ID를 사용합니다. 스키마에서 pane_id을 선택 사항으로 만드는 메서드는 생략될 때 서버의 활성 포커스 패널을 사용합니다. pane.move에는 항상 pane_id 소스가 필요합니다.

pane.send_keys 및 pane.send_input.keys은 Herdr 키 콤보 문자열을 허용합니다. 일반 출력 가능한 키, enter 및 esc과 같은 특수 키, ctrl+h, control+j, alt+x 및 shift+tab과 같은 수정 코드, f1과 같은 기능 키, minus 및 plus과 같은 명명된 구두점. prefix+ 바인딩 문자열을 허용하지 않습니다.

{"id":"req_current","method":"pane.current","params":{"caller_pane_id":"w1:p1"}}
{"id":"req_layout","method":"pane.layout","params":{"pane_id":"w1:p1"}}
{"id":"req_neighbor","method":"pane.neighbor","params":{"pane_id":"w1:p1","direction":"right"}}
{"id":"req_edges","method":"pane.edges","params":{"pane_id":"w1:p1"}}
{"id":"req_focus","method":"pane.focus_direction","params":{"direction":"right"}}
{"id":"req_resize","method":"pane.resize","params":{"pane_id":"w1:p1","direction":"right","amount":0.1}}
{"id":"req_zoom","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"toggle"}}
{"id":"req_input","method":"pane.input.set","params":{"pane_id":"w1:p1","right_click":"pane"}}
{"id":"req_split","method":"pane.split","params":{"direction":"right","ratio":0.333,"right_click":"pane","env":{"HERDR_ROLE":"tests"}}}
{"id":"req_process","method":"pane.process_info","params":{"pane_id":"w1:p1"}}

pane.current은 단일 PaneInfo을 반환합니다. caller_pane_id가 있으면 Herdr는 해당 패널을 반환합니다. 생략되면 Herdr는 활성 초점 패널을 반환합니다.

pane.input.set은 한 패널에 대해 right_click을 herdr 또는 pane로 설정합니다. herdr이 기본값입니다. pane는 응용 프로그램이 터미널 마우스 보고를 요청할 때 수정되지 않은 오른쪽 클릭 누르고 끌기 동작을 전달합니다. 그렇지 않으면 Herdr는 해당 패널 메뉴로 돌아갑니다. 패널 프레임을 마우스 오른쪽 버튼으로 클릭하면 항상 Herdr의 메뉴가 열립니다. pane.split은 새로 생성된 패널에 대해 동일한 선택적 right_click 값을 허용합니다.

PaneInfo에는 터미널 스크롤 메트릭을 사용할 수 있는 경우 scroll이 포함됩니다.

{
  "offset_from_bottom": 12,
  "max_offset_from_bottom": 240,
  "viewport_rows": 30
}

클라이언트는 offset_from_bottom == 0을 최하위 상태로 처리할 수 있습니다.

애플리케이션과 플러그인은 해당 패널의 터미널 출력을 통해 표준 Kitty 그래픽 프로토콜을 내보내야 합니다. Herdr는 호환 가능한 외부 터미널에서 이미지 배치, 클리핑 및 가시성을 관리합니다.

외부 소켓 패널 오버레이 API가 제거되었습니다. pane.graphics.info, pane.graphics.set, pane.graphics.clear 및 pane.graphics.stream을 더 이상 사용할 수 없습니다. 대체 소켓 이미지 API가 없습니다. 이전 서버와의 내부 회선 호환성은 이러한 공용 메서드를 복원하지 않습니다.

pane.layout은 workspace_id, tab_id, zoomed, 외부 area, focused_pane_id, 패널 사각형 및 분할 사각형/비율이 포함된 탭 레이아웃 스냅샷을 반환합니다. pane.neighbor 및 pane.edges에는 동일한 레이아웃 스냅샷이 포함되어 있으므로 클라이언트는 비공개 레이아웃 상태 없이 다음 결정을 내릴 수 있습니다.

pane.process_info은 패널의 셸 pid, 사용 가능한 경우 포그라운드 프로세스 그룹 ID를 반환하고, 플랫폼이 노출할 경우 pid, 이름, argv/cmdline 및 cwd가 있는 포그라운드 프로세스를 반환합니다.

layout.export은 휴대용 탭 레이아웃 트리를 반환합니다. 활성 탭을 내보내려면 tab_id 및 pane_id를 생략하고, 해당 탭을 내보내려면 tab_id을 전달하고, 해당 패널을 포함하는 탭을 내보내려면 pane_id을 전달합니다.

{"id":"req_export","method":"layout.export","params":{"tab_id":"w1:t1"}}

응답에는 workspace_id, tab_id, zoomed, focused_pane_id 및 root가 포함됩니다. root는 pane 및 split 노드의 BSP 트리입니다. 패널 노드에는 pane_id, label, cwd 및 argv command이 포함될 수 있습니다. 분할 노드는 direction(right 또는 down), ratio, first 및 second을 사용합니다.

layout.apply은 선언적 트리에서 새로운 탭을 만듭니다. tab_id이 제공되면 Herdr는 먼저 교체 탭을 생성한 다음 이전 탭을 닫습니다. 이렇게 하면 구조, 레이블, cwd, env 및 선택적 argv 명령이 복원됩니다. 라이브 PTY, 스크롤백 또는 실행 중인 프로세스는 보존되지 않습니다.

{
  "id": "req_apply",
  "method": "layout.apply",
  "params": {
    "workspace_id": "wabc",
    "tab_label": "dev",
    "focus": true,
    "root": {
      "type": "split",
      "direction": "right",
      "ratio": 0.65,
      "first": {
        "type": "pane",
        "label": "editor",
        "cwd": "/repo"
      },
      "second": {
        "type": "pane",
        "label": "tests",
        "cwd": "/repo",
        "command": ["sh", "-c", "just test"],
        "env": { "HERDR_ROLE": "tests" }
      }
    }
  }
}

layout.set_split_ratio은 탭 레이아웃의 기존 분할을 업데이트합니다. 응답은 업데이트된 휴대용 layout의 type: "layout_split_ratio_set"입니다.

{"id":"req_ratio","method":"layout.set_split_ratio","params":{"tab_id":"w1:t1","path":[],"ratio":0.6}}

프로세스 시작 메서드는 env 개체를 허용합니다. Herdr는 해당 키/값 쌍을 새로 시작된 프로세스에만 적용합니다. Herdr는 또한 HERDR_SOCKET_PATH, HERDR_ENV=1, HERDR_WORKSPACE_ID, HERDR_TAB_ID 및 HERDR_PANE_ID를 관리되는 패널 프로세스에 주입합니다. Herdr 관리 변수는 호출자가 제공한 환경과 충돌할 때 신뢰할 수 있습니다.

pane.swap은 방향성 및 명시적 형식을 지원합니다.

{"id":"req_swap_dir","method":"pane.swap","params":{"pane_id":"w1:p1","direction":"right"}}
{"id":"req_swap_explicit","method":"pane.swap","params":{"source_pane_id":"w1:p1","target_pane_id":"w1:p2"}}

스왑은 동일한 탭에서만 가능합니다. 분할 모양, 분할 비율, 패널 ID 및 실행 중인 프로세스를 유지합니다. 응답은 changed, 선택 사항 reason, source_pane_id, 선택 사항 target_pane_id, focused_pane_id 및 layout이 포함된 type: "pane_swap"입니다. 이유 값은 no_neighbor, same_pane, not_found 및 cross_tab입니다. 탭이 확대되면 스왑은 확대/축소를 활성 상태로 유지하고 숨겨진 전체 탭 레이아웃을 변경합니다.

pane.move은 실행 중인 패널을 다른 탭, 새 탭 또는 새 작업 공간으로 이동합니다.

{"id":"req_move_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"tab","tab_id":"w1:t2","target_pane_id":"w1:p3","split":"right","ratio":0.5},"focus":true}}
{"id":"req_move_new_tab","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_tab","workspace_id":"w1","label":"logs"},"focus":true}}
{"id":"req_move_new_workspace","method":"pane.move","params":{"pane_id":"w1:p2","destination":{"type":"new_workspace","label":"logs","tab_label":"main"},"focus":true}}

기존 탭 이동에는 split: "right" | "down"이 필요합니다. target_pane_id은 선택 사항이며 기본적으로 대상 탭의 포커스 패널로 설정됩니다. 동일한 탭 레이아웃 변경 사항은 pane.swap로 유지됩니다. 소스 탭으로 이동하면 reason: "same_tab"와 함께 changed: false이 반환됩니다. 확대된 소스 또는 대상 탭과 관련된 이동은 reason: "zoomed_tab"과 함께 changed: false을 반환합니다.

응답은 changed, 선택적 reason, previous_pane_id, previous_workspace_id, previous_tab_id, 이동된 pane, 선택적 source_layout, target_layout, 선택적 생성된 작업 공간 또는 탭 레코드, 선택적 닫힌 작업 공간 또는 탭 ID 및 focused_pane_id가 포함된 type: "pane_move"입니다. 작업 공간 간 이동은 내부 패널과 터미널을 활성 상태로 유지하지만 대상 작업 공간에 새 공개 패널 ID를 할당합니다. 구독자는 pane.moved을 들을 수 있습니다. Herdr는 이동된 터미널 프로세스에 대해 가짜 패널 닫기/생성 이벤트를 생성하지 않습니다.

pane.zoom은 대상 패널 탭의 확대/축소를 전환, 활성화 또는 비활성화합니다.

{"id":"req_zoom_toggle","method":"pane.zoom","params":{"pane_id":"w1:p1"}}
{"id":"req_zoom_on","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"on"}}
{"id":"req_zoom_off","method":"pane.zoom","params":{"pane_id":"w1:p1","mode":"off"}}

pane_id을 생략하면 서버의 활성 초점 패널을 대상으로 합니다. 응답은 changed, zoom_changed, focus_changed, 선택 사항인 reason, pane_id, focused_pane_id, zoomed 및 layout이 포함된 type: "pane_zoom"입니다. changed은 확대/축소 상태나 초점이 변경된 경우 true입니다. 이유 값은 single_pane, already_zoomed 및 already_unzoomed입니다.

notification.show에 대한 CLI 래퍼는 다음과 같습니다.

herdr notification show "build failed" --body "api workspace" --position top-left --sound request

구성된 토스트 전달을 통해 사용자 알림을 표시합니다.

{"id":"req_notify","method":"notification.show","params":{"title":"build failed","body":"api workspace","position":"top-left","sound":"request"}}

title은 필수이며 제어 문자와 반복되는 공백이 제거된 후 표시되는 텍스트를 포함해야 합니다. body은 선택 사항입니다. Herdr는 개행, 탭, 캐리지 리턴 및 반복되는 공백을 공백으로 축소한 다음 알림 텍스트를 title의 경우 80자로, body의 경우 240자로 자릅니다. 비어 있는 정리된 title는 invalid_params를 반환합니다. position은 선택 사항이며 ui.toast.delivery = "herdr"인 경우에만 적용됩니다. 데스크탑 위치는 전체 Herdr 프레임을 기준으로 하며 생략된 위치는 ui.toast.herdr.position을 사용합니다. 터미널, 시스템 및 배송 불량은 position을 무시합니다. sound은 선택 사항이며 none, done 또는 request일 수 있습니다. 기본값은 none이며 알림이 표시될 때만 재생됩니다.

응답은 표시된 항목이 있는지 보고합니다.

{"id":"req_notify","result":{"type":"notification_show","shown":true,"reason":"shown"}}

가능한 이유는 shown, disabled, rate_limited, no_foreground_client 및 busy입니다. disabled는 ui.toast.delivery = "off"을 의미합니다. busy은 기존 인앱 토스트가 교체되지 않았음을 의미합니다. 터미널 및 시스템 전달은 현재 포그라운드에 연결된 Herdr 클라이언트를 통해 최선의 노력을 다합니다.

포그라운드 클라이언트의 외부 터미널 창 제목을 설정하거나 지웁니다.

{"id":"req_title","method":"client.window_title.set","params":{"title":"herdr api"}}
{"id":"req_title_clear","method":"client.window_title.clear","params":{}}

client.window_title.clear은(는) 제목을 ui.window_title에게 돌려줍니다. 응답은 changed 및 이유 set, cleared 또는 no_foreground_client을 포함하는 type: "client_window_title"입니다.

Worktree 메서드는 Git 체크아웃을 Herdr 작업 공간으로 관리합니다. worktree.create은 결제를 생성하고 새 workspace, tab, root_pane 및 worktree 레코드를 반환합니다. 요청한 분기가 이미 로컬에 존재하는 경우 해당 분기를 체크아웃합니다. 그렇지 않으면 요청된 기본 또는 HEAD에서 분기를 만듭니다. worktree.open은 기존 체크아웃을 열거나 이미 열려 있는 작업 공간을 반환합니다. worktree.remove은 연결된 하위 작업 공간에 대해 git worktree remove을 실행하고 분기를 삭제하지 않습니다.

소스 작업 공간에서 작업 트리를 만듭니다.

{"id":"req_1","method":"worktree.create","params":{"workspace_id":"w1","branch":"worktree/api","focus":false}}

기존 결제를 엽니다.

{"id":"req_2","method":"worktree.open","params":{"workspace_id":"w1","branch":"worktree/api","focus":true}}

연결된 결제 제거:

{"id":"req_3","method":"worktree.remove","params":{"workspace_id":"2","force":false}}

worktree.list, worktree.create 및 worktree.open에는 workspace_id 또는 cwd 중 하나만 사용하세요. 활성 작업 공간을 사용하려면 둘 다 생략하세요. worktree.open에는 path 또는 branch 중 하나만 사용하세요. 원시 소켓 cwd 및 path 값은 절대값이어야 합니다. CLI는 요청을 보내기 전에 상대 --cwd 및 --path 값을 확장합니다. 작업 공간 응답에는 작업 공간이 Herdr 작업 트리 그룹에 속하는 경우 선택적 worktree 출처가 포함됩니다. 작업 트리 명령은 기존 작업 공간이 작업 트리 출처를 얻거나 변경할 때 workspace.updated을 내보낼 수 있습니다.

Worktree 명령은 수명 주기 이벤트도 내보냅니다. worktree.create은(는) workspace.created, tab.created, pane.created 및 worktree.created을 방출합니다. worktree.open는 worktree.opened을 내보내고 새 Herdr 작업 공간을 열 때 작업 공간/탭/창 생성 이벤트도 내보냅니다. worktree.remove은 worktree.removed을 방출합니다. 연결된 작업 공간이 아직 열려 있으면 workspace.closed도 내보냅니다.

workspace.close은 해당 매개변수에 "close_group": true이 포함되지 않는 한 연결된 작업 트리 작업 공간이 열려 있는 동안 기본 작업 공간 닫기를 거부하고, 명시적인 그룹 의도가 누락된 경우 workspace_group_close_required를 반환합니다. 명시적 그룹 닫기는 닫는 각 작업 공간에 대해 하나의 workspace.closed 이벤트를 발생시킵니다.

agent.view.set은 기본 제공 에이전트 보기에 대한 하나의 임시 선언적 프로젝션을 설치합니다. 에이전트 사실이나 현재 UI 컨텍스트가 변경될 때마다 투영이 재평가됩니다. 확장 및 축소 사이드바, 모바일 에이전트 목록, 마우스 대상, 인덱스 포커스, 다음/이전 에이전트 탐색을 제어합니다. agent.list, 알림, 감지 또는 전역 주의 횟수는 변경되지 않습니다.

현재 표시된 공간에 있는 에이전트나 다른 곳에 주의가 필요한 에이전트를 표시한 다음 주의 및 가장 최근 상태 전환을 기준으로 정렬합니다.

{
  "id": "view_set",
  "method": "agent.view.set",
  "params": {
    "source": "plugin:example.agent-views",
    "label": "focus",
    "filter": {
      "op": "any",
      "filters": [
        {
          "op": "eq",
          "field": "workspace_id",
          "value": {"context": "current_workspace_id"}
        },
        {
          "op": "in",
          "field": "status",
          "values": ["blocked", "done"]
        }
      ]
    },
    "sort": [
      {"field": "attention", "order": "desc"},
      {"field": "state_change_seq", "order": "desc"}
    ]
  }
}

필터 노드는 op 값 all, any, not, eq, in 또는 exists을 사용합니다. 기본 제공 필터 필드는 status, workspace_id, tab_id, pane_id, agent, seen 및 state_change_seq입니다. 플러그인이 보고하는 패널 메타데이터를 필터링하려면 {"token":"name"}을 필드로 사용하세요. 값은 문자열, 부울, 부호 없는 숫자 또는 컨텍스트 개체입니다. 컨텍스트 값은 current_workspace_id 및 current_tab_id이며 일치하는 ID 필드와만 비교할 수 있습니다. 저장된 기기 클라이언트에서는 선택한 서버의 보기가 통합된 에이전트 목록에 적용됩니다. 현재 작업 공간 및 탭 컨텍스트에는 선택한 시스템이 포함되므로 다른 시스템의 동일한 ID는 일치하지 않습니다. status이 blocked인 것과 같은 독립 필터 분기는 연결된 모든 시스템의 에이전트와 계속 일치합니다. 유효 상태 값은 idle, working, blocked, done 및 unknown입니다. done은 유휴 상태이고 아직 표시되지 않음을 의미합니다.

정렬 필드는 workspace_order, tab_order, pane_order, attention, status, agent, seen, state_change_seq 또는 {"token":"name"}입니다. 정렬은 안정적이고 순서대로 평가되며 asc 또는 desc을 허용합니다. 누락된 값은 현재 값 뒤에 유지됩니다. sort을 생략하면 기존 ui.agent_panel_sort 정책이 활성 상태로 유지됩니다. 사용자 정의 정렬은 구성을 다시 작성하지 않고 해당 정책을 일시적으로 대체합니다.

source은 소유자를 식별합니다. 플러그인은 plugin:<HERDR_PLUGIN_ID>을 사용합니다. Herdr는 플러그인이 없거나 비활성화된 경우 플러그인 소유 세트를 거부합니다. 다른 발신자는 자신의 plugin:이 아닌 소스를 사용할 수 있습니다. 성공적인 세트는 이전 보기를 원자적으로 대체합니다. 보기는 삭제, 교체, 소유 플러그인이 비활성화, 링크 해제 또는 제거되거나 서버가 종료될 때까지 지속됩니다. 지속 가능한 동작을 원하는 플러그인은 쿼리를 HERDR_PLUGIN_STATE_DIR에 저장하고 [[startup]] 훅에서 다시 적용해야 합니다.

무조건 지우거나 명명된 소스가 여전히 뷰를 소유하고 있는 경우에만 지우십시오.

{"id":"view_clear","method":"agent.view.clear","params":{}}
{"id":"view_clear_owned","method":"agent.view.clear","params":{"source":"plugin:example.agent-views"}}

소스 불일치로 인해 활성 보기가 변경되지 않습니다. 응답을 설정하고 지우려면 type: "agent_view"을 사용하고 active, source 및 선택 사항인 label을 보고하세요.

플러그인 API는 실행 가능한 워크플로 도구를 위한 초기 인터페이스입니다. 플러그인은 herdr-plugin.toml 매니페스트가 포함된 패키지입니다. 매니페스트는 시작 훅, 공유 가능한 작업, 이벤트 훅, 터미널 패널 진입점 및 링크 처리기를 선언합니다. 시작 훅는 API가 준비되면 복원 후 한 번 실행됩니다. 작업 및 패널은 매니페스트 전용입니다. 런타임 작업 등록 및 런타임 argv 패널 생성은 v1의 일부가 아닙니다.

설치되고 연결된 플러그인은 다시 시작해도 유지됩니다. Herdr는 plugin.link, plugin.unlink, plugin.enable 및 plugin.disable에 session.json과 함께 plugins.json 레지스트리 파일을 작성합니다. herdr plugin install 및 herdr plugin link CLI도 Herdr가 실행되지 않을 때 동일한 레지스트리를 작성한 다음 시작 시 이를 자동으로 로드합니다. 시작 시 Herdr는 원래 경로에서 각 매니페스트를 다시 읽습니다. 파일이 없거나 구문 분석할 수 없는 경우 항목은 warnings 필드와 함께 유지되므로 plugin.list이 해당 항목을 표시합니다.

Herdr는 링크 타임에 알려진 이벤트 이름에 대해 이벤트 훅 on 값의 유효성을 검사합니다. 인식할 수 없는 이름은 링크를 차단하지 않지만 반환된 플러그인 정보에는 경고(예: "unknown event 'worktree.craeted'")가 포함됩니다. plugin.link 및 plugin.list 응답에서 warnings 필드를 확인하세요.

로컬 플러그인 매니페스트를 연결합니다.

{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/path/to/plugin","enabled":true}}

plugin.link은(는) 선택적 source 메타데이터도 허용합니다. CLI는 GitHub에서 설치할 때 이를 사용하므로 plugin.list는 원본, 요청된 참조, 해결된 커밋 및 관리되는 체크아웃 경로를 표시할 수 있습니다.

{"id":"req_plugin_link","method":"plugin.link","params":{"path":"/managed/plugin/herdr-plugin.toml","enabled":true,"source":{"kind":"github","owner":"ogulcancelik","repo":"herdr-plugin-examples","subdir":"worktree-bootstrap","requested_ref":"main","resolved_commit":"abc123","managed_path":"/data/plugins/github/<managed-checkout>","installed_unix_ms":1780000000000}}}

경로는 herdr-plugin.toml을 포함하는 플러그인 디렉터리이거나 직접 매니페스트 경로일 수 있습니다. 매니페스트 모양은 다음과 같습니다.

id = "example.worktree-bootstrap"
name = "Worktree Bootstrap"
version = "0.1.0"
min_herdr_version = "0.7.0"
description = "Prepare new worktrees"
platforms = ["linux", "macos", "windows"]


[[build]]
command = ["bun", "install"]


[[actions]]
id = "bootstrap"
title = "Bootstrap worktree"
contexts = ["workspace"]
command = ["bun", "run", "bootstrap.ts"]


[[events]]
on = "worktree.created"
command = ["bun", "run", "bootstrap.ts"]


[[panes]]
id = "board"
title = "Worktree board"
placement = "overlay"
command = ["bun", "run", "board.ts"]


[[link_handlers]]
id = "github-issue"
title = "Open GitHub issue"
pattern = "^https://github\\.com/[^/]+/[^/]+/(issues|pull)/[0-9]+$"
action = "bootstrap"

min_herdr_version가 필요합니다. 필드가 누락되었거나 유효하지 않거나 실행 중인 Herdr 바이너리보다 최신인 경우 서버는 플러그인 연결을 거부합니다.

플러그인이 지원하는 OS 식별자(linux, macos, windows)를 사용하여 최상위 수준에서 platforms을 선언합니다. 로컬 개발에서는 platforms 생략이 허용됩니다. plugin.link 성공했지만 응답에 경고가 포함되었습니다. 개별 빌드 명령, 작업, 이벤트 훅, 패널 및 링크 처리기는 자체 platforms을 선언하여 플러그인 수준 목록을 재정의할 수 있습니다. 생략하면 플러그인에서 상속됩니다. 작업을 호출하거나 유효한 플랫폼에 현재 OS가 포함되지 않은 패널을 열면 platform_unsupported 오류가 반환됩니다.

연결된 플러그인을 나열, 활성화, 비활성화 또는 연결 해제합니다.

{"id":"req_plugin_list","method":"plugin.list","params":{}}
{"id":"req_plugin_disable","method":"plugin.disable","params":{"plugin_id":"example.worktree-bootstrap"}}
{"id":"req_plugin_enable","method":"plugin.enable","params":{"plugin_id":"example.worktree-bootstrap"}}
{"id":"req_plugin_unlink","method":"plugin.unlink","params":{"plugin_id":"example.worktree-bootstrap"}}

작업은 연결된 매니페스트에서 해결됩니다. plugin.action.list은 설치된 플러그인 전반에 걸쳐 모든 작업을 반환합니다. plugin_id을 필터링에 전달합니다.

{"id":"req_plugin_actions","method":"plugin.action.list","params":{}}
{"id":"req_plugin_actions_filtered","method":"plugin.action.list","params":{"plugin_id":"example.worktree-bootstrap"}}

plugin.action.list은 플러그인 수준 상속을 적용한 후 각 작업의 유효한 platforms을 반환합니다.

정규화된 ID 또는 순수 작업 ID로 작업을 호출합니다.

{"id":"req_plugin_invoke","method":"plugin.action.invoke","params":{"action_id":"example.worktree-bootstrap.bootstrap","context":{"invocation_source":"keybinding"}}}

plugin.action.invoke은 매니페스트 작업을 해결하고 매니페스트 명령을 시작하며 Herdr 기반 호출 컨텍스트와 시작된 명령 로그 레코드를 반환합니다. 누락된 컨텍스트 필드는 활성 작업 공간, 탭, 포커스 패널, 작업 트리 출처 및 요청 ID에서 채워집니다. 비활성화된 플러그인에서 작업을 호출하면 plugin_disabled 오류가 반환됩니다.

Herdr는 HERDR_SOCKET_PATH, HERDR_BIN_PATH, HERDR_ENV=1, HERDR_PLUGIN_ID, HERDR_PLUGIN_ROOT, HERDR_PLUGIN_CONFIG_DIR, HERDR_PLUGIN_STATE_DIR, HERDR_PLUGIN_CONTEXT_JSON 및 사용 가능한 HERDR_WORKSPACE_ID, HERDR_TAB_ID 및 HERDR_PANE_ID 값을 주입합니다. 작업 명령도 HERDR_PLUGIN_ACTION_ID을 수신합니다. 이벤트 훅는 HERDR_PLUGIN_EVENT 및 HERDR_PLUGIN_EVENT_JSON을 수신합니다. 패널 명령은 HERDR_PLUGIN_ENTRYPOINT_ID을 수신합니다.

최근 작업 및 이벤트 명령 로그를 나열합니다.

{"id":"req_plugin_logs","method":"plugin.log.list","params":{"plugin_id":"example.worktree-bootstrap","limit":20}}

Herdr가 worktree.created과 같은 일치하는 이벤트 이름을 내보낼 때 활성화된 설치된 플러그인에 대해 이벤트 훅가 실행됩니다.

v1에는 Herdr 관리 플러그인 스토리지 API가 없습니다. HERDR_PLUGIN_CONFIG_DIR 및 HERDR_PLUGIN_STATE_DIR은 경로 검색 전용입니다. 플러그인은 파일, 스키마, 마이그레이션 및 정리를 소유합니다.

관리형 터미널 UI를 엽니다.

{"id":"req_plugin_pane","method":"plugin.pane.open","params":{"plugin_id":"example.board","entrypoint":"board","placement":"zoomed","target_pane_id":"w1:p1","env":{"HERDR_ROLE":"board"},"focus":true}}

plugin.pane.open에는 설치 및 활성화된 플랫폼 호환 플러그인이 필요하며 요청된 매니페스트 [[panes]] 진입점을 argv 지원 터미널 패널로 실행합니다. 매니페스트 패널 placement의 기본값은 overlay입니다. placement 요청은 overlay, popup, split, tab 또는 zoomed로 매니페스트를 재정의합니다. 오버레이 및 팝업 배치는 활성 타일 패널을 실행 컨텍스트로 사용합니다. 팝업 터미널은 세션 모달이며 탭 레이아웃을 변경하지 않습니다. 선택적 width 및 height 필드는 외부 크기를 "80%"와 같은 터미널 셀 또는 백분율로 설정합니다. 생략된 치수는 기본적으로 터미널 크기의 절반으로 설정되며 너무 작은 값은 팝업 최소값으로 고정됩니다. 팝업에는 패널 ID가 없고 모든 pane.* 및 에이전트 API 외부에 유지되며 패널 수명 주기 이벤트가 발생하지 않고 플러그인 포커스 컨텍스트가 기본 타일 패널에 남아 있으며 HERDR_PANE_ID을 해당 프로세스로 내보내지 않습니다. 팝업 실행이 ok을 반환합니다. popup.close은 활성 팝업을 닫고 아무것도 없으면 popup_not_open을 반환합니다. 분할 및 확대된 패널은 기존 패널을 대상으로 합니다. 탭 패널은 작업 공간을 대상으로 할 수 있습니다. 분할, 탭, 확대 및 오버레이 패널은 일반 Herdr 창처럼 작동하며 plugin.pane.focus 및 plugin.pane.close은 해당 패널에서 계속 작동합니다.

Herdr는 로컬 소켓을 통해 개행으로 구분된 JSON을 사용합니다. Unix에서 해당 소켓은 Unix 도메인 소켓입니다. Windows에서는 명명된 파이프입니다.

한 줄에 하나의 요청을 보냅니다.

{"id":"req_1","method":"ping","params":{}}

성공적인 응답에는 동일한 id이 포함됩니다.

{"id":"req_1","result":{"type":"pong"}}

JSON 디코딩에 도달하는 요청 라인의 경우 오류 응답은 메서드나 매개변수가 유효하지 않은 경우를 포함하여 요청의 id도 반영합니다. JSON이 유효하지 않거나 명확한 최상위 문자열 id이 없는 경우 오류 응답은 빈 id를 사용합니다. 잘못된 UTF-8과 같은 전송 오류는 응답 없이 연결을 닫을 수 있습니다.

이벤트 구독은 초기 응답 후에도 연결을 열린 상태로 유지합니다.

기본 소켓은 Herdr 구성 디렉터리에 있습니다.

명명된 세션에는 별도의 소켓이 있습니다.

~/.config/herdr/herdr.sock
~/.config/herdr/sessions/<name>/herdr.sock

해결 순서:

1. 명시적 CLI --session <name>
2. HERDR_SOCKET_PATH
3. HERDR_SESSION=<name>
4. 기본 세션 소켓

낮은 수준 재정의에만 HERDR_SOCKET_PATH을 사용하세요.

플러그인의 경우 이식 가능한 Windows 동작이 필요할 때 HERDR_BIN_PATH 및 CLI 래퍼를 호출하는 것이 좋습니다. 원시 소켓 클라이언트는 플랫폼 고유 로컬 소켓 형식을 사용합니다.

통합 보고서 에이전트 상태는 pane.report_agent입니다.

{
  "id": "req_1",
  "method": "pane.report_agent",
  "params": {
    "pane_id": "w1:p1",
    "source": "custom:docs",
    "agent": "docs-bot",
    "state": "working",
    "message": "building docs"
  }
}

state은 의미론적 에이전트 상태를 전달하고 대기, 알림 및 롤업에 영향을 줍니다. 메타데이터를 통해 표시 전용 값을 별도로 보고합니다.

세션 전용 공식 통합은 pane.report_agent_session을 사용하여 기본 세션 참조를 보고합니다. 상태 보고 통합에는 pane.report_agent에 기본 세션 참조가 계속 포함될 수 있습니다. 상태 독립적인 세션 보고서는 대기, 알림 또는 롤업에 영향을 주지 않습니다.

{
  "id": "req_2",
  "method": "pane.report_agent_session",
  "params": {
    "pane_id": "w1:p1",
    "source": "herdr:codex",
    "agent": "codex",
    "agent_session_id": "..."
  }
}

두 방법 모두 Herdr 서버를 다시 시작한 후 보고자의 현재 세션을 재개하는 명령과 함께 선택적 resume_argv 배열을 허용합니다. 첫 번째 요소는 경로가 아닌 일반 명령 이름이어야 합니다. 최대 64개 요소와 총 8KiB를 허용하며 요소에는 아포스트로피나 ​​제어 문자가 포함될 수 없습니다. 잘못된 값은 invalid_resume_argv과 함께 실패하고 보고서가 적용되지 않습니다. 사용자 지정 에이전트는 명령을 연결하기 전에 pane.report_agent를 통해 패널을 유지해야 합니다. 그렇지 않으면 resume_not_accepted으로 인해 요청이 실패합니다. Herdr는 동일한 source 및 agent이 패널을 보유하는 동안에만 명령을 유지하며 해당 에이전트에 대한 Herdr의 내장 재개 명령보다 우선합니다. 이전 Herdr 버전은 필드를 무시합니다.

{
  "id": "req_3",
  "method": "pane.report_agent_session",
  "params": {
    "pane_id": "w1:p1",
    "source": "custom:my-agent",
    "agent": "my-agent",
    "agent_session_id": "...",
    "resume_argv": ["my-agent", "--resume", "..."]
  }
}

pane.get, pane.list, agent.get 및 agent.list은 Herdr에 저장된 기본 세션 참조가 있는 경우 읽기 전용 agent_session 개체를 노출합니다.

{
  "agent_session": {
    "source": "herdr:codex",
    "agent": "codex",
    "kind": "id",
    "value": "..."
  }
}

기본 세션 참조가 저장되지 않은 경우 필드가 생략됩니다.

Herdr가 현재 패널 PTY를 제어하는 프로세스의 cwd를 확인할 수 있는 경우 pane.get, pane.list, agent.get 및 agent.list도 foreground_cwd을 노출합니다. 기존 cwd 필드는 레이블, cwd 동작 및 복원된 세션 상태에 사용되는 창/작업 공간 cwd로 유지됩니다.

PaneInfo 및 AgentInfo은 선택적 terminal_title 및 terminal_title_stripped 필드를 노출합니다. terminal_title는 안전 표준화 이후 최신 OSC 0/2 타이틀입니다. terminal_title_stripped는 인식된 선행 활동 또는 스피너 문자 모양 하나와 뒤따르는 공백을 제거합니다. 이러한 서버 소유 값은 콜드 재시작 시 일시적이며 메타데이터 title 및 의미 체계 에이전트 상태와 무관합니다.

사용자 훅가 Herdr 통합에서 수명 주기 상태를 인계받지 않고 프레젠테이션을 사용자 정의하려는 경우 pane.report_metadata을 사용하세요.

{
  "id": "req_2",
  "method": "pane.report_metadata",
  "params": {
    "pane_id": "w1:p1",
    "source": "user:claude-title",
    "agent": "claude",
    "title": "Refactor auth middleware",
    "display_agent": "Claude: auth",
    "state_labels": {
      "working": "refactoring auth",
      "idle": "ready",
      "done": "review ready"
    },
    "tokens": {
      "summary": "refactor auth",
      "model": "opus"
    },
    "ttl_ms": 3600000
  }
}

메타데이터 보고서는 표시 전용입니다. 유효한 메타데이터는 패널 제목, 표시된 에이전트 이름, 표시되는 상태 레이블 및 임의의 명명된 토큰을 재정의할 수 있습니다. working, blocked, idle, 대기, 알림 및 롤업은 여전히 ​​의미론적 상태에서 발생합니다. 기본 세션 복원은 저장된 공식 세션 참조에서 이루어집니다. agent은 권한 있는 에이전트 레이블에 대한 프레젠테이션 필드의 선택적 보호입니다. applies_to_source도 마찬가지로 활성 수명 주기 권한 소스로부터 프레젠테이션 필드를 보호합니다. 이러한 가드는 토큰 패치에 적용되지 않습니다. 토큰 보고자는 삭제 및 TTL 새로 고침을 소유합니다. 표시되는 이름을 변경하려면 display_agent을 사용하세요. state_labels 키는 idle, working, blocked, done 또는 unknown이어야 합니다.

토큰 맵은 리소스별 패치입니다. 문자열은 키를 설정하고, JSON null은 이를 지우고, 생략된 키는 변경되지 않은 채로 유지됩니다. 가장 최근에 승인된 업데이트가 적용됩니다. 선택적 TTL은 해당 보고서에서 업데이트된 토큰 키에 독립적으로 적용됩니다. 패널 토큰은 패널 및 에이전트 가져오기/목록 응답에 의해 노출되며 에이전트 사이드바 행에서 $name로 렌더링될 수 있습니다. 보고서에는 최대 16개의 토큰 키가 언급될 수 있으며 패널이나 작업 공간은 최대 32개의 키를 보유할 수 있습니다. 토큰 이름은 1~32개의 ASCII 문자, 숫자, 밑줄 또는 하이픈으로 구성됩니다.

Workspace 토큰은 동일한 계약을 사용합니다.

{"id":"req_3","method":"workspace.report_metadata","params":{"workspace_id":"w1","source":"user:jj","tokens":{"jj_status":"2 changes","old":null},"ttl_ms":5000}}

Workspace 가져오기/목록 응답은 결과 tokens 맵을 노출하고 Space 사이드바 행은 $jj_status과 같은 값을 렌더링할 수 있습니다. 변경 사항 및 TTL 만료는 최신 작업 공간 스냅샷으로 workspace.metadata_updated를 내보냅니다. 이 메타데이터 이벤트는 API 구독자가 사용할 수 있지만 플러그인 이벤트 훅를 호출하지 않습니다.

프레젠테이션 텍스트는 저장되기 전에 정규화됩니다. Herdr는 주변 공백을 자르고 제어 문자를 제거하고 title, display_agent, 각 상태 레이블 및 토큰 값을 80자로 제한합니다. 정규화된 빈 토큰 값은 해당 키를 지웁니다.

source 및 applies_to_source은 소스 식별자입니다. 80자 이하여야 하며 ASCII 문자, 숫자, 콜론, 점, 밑줄 및 하이픈만 포함할 수 있습니다.

단기 메타데이터에는 ttl_ms을 사용하세요. 1에서 86400000밀리초 사이여야 합니다. 대체되거나 지워지거나 창/작업 공간이 닫힐 때까지 유지되어야 하는 메타데이터에 대해 ttl_ms을 생략합니다. 프리젠테이션 필드는 기존 소스 범위 만료 동작을 유지합니다. 호출에 의해 업데이트된 각 토큰은 자체 기한을 받습니다. 서버를 다시 시작한 후에는 토큰 메타데이터가 복원되지 않습니다.

훅가 업데이트를 잘못된 순서로 보낼 수 있는 경우 seq을 사용하세요. 동일한 source의 경우 마지막으로 허용된 시퀀스보다 작거나 같은 시퀀스 번호가 있는 보고서는 API에서 허용되지만 패널 상태에서는 무시됩니다. 패널 또는 작업 공간은 수명 동안 최대 32개의 개별 소스로부터 순서화된 토큰 보고서를 허용합니다. 지우거나 만료해도 해당 소스 슬롯은 해제되지 않습니다.

장기 스트림이 필요한 경우 이벤트를 구독하세요.

{
  "id": "sub_1",
  "method": "events.subscribe",
  "params": {
    "subscriptions": [
      { "type": "pane.agent_status_changed", "pane_id": "w1:p1", "agent_status": "blocked" }
    ]
  }
}

첫 번째 응답은 구독을 확인합니다. 이후 행은 푸시된 이벤트입니다. 모든 항목은 유효해야 합니다. 참조된 패널이 존재하지 않으면 Herdr는 오류와 함께 전체 요청을 거부하고 연결을 닫습니다. 다른 항목이 구독되었다고 가정하는 대신 패널 목록을 새로 고치고 다시 시도하세요. 라이프사이클 구독은 요청이 수락되면 시작되며 해당 시점 이전에 보관된 이벤트를 재생하지 않습니다.

수명 주기 및 에이전트 상태 이벤트는 각 구독 내에서 순서대로 제한된 배치로 배출됩니다. 이벤트 기록은 지속성이 없습니다. 구독이 초기화되는 동안을 포함하여 구독자가 보관된 기록보다 뒤떨어지면 서버는 원래 요청 id 및 error.code: "events_lost"과 함께 오류 응답을 보낸 다음 누락된 이벤트를 자동으로 계속하는 대신 해당 구독 연결을 닫습니다. 다른 클라이언트는 연결된 상태로 유지됩니다. 기록은 이벤트 유형 전체에서 공유되므로 제거된 이벤트가 이 구독의 필터와 일치하지 않는 경우에도 오버런이 보고됩니다.

events_lost에서는 캐시된 상태를 오래된 것으로 처리합니다. 새 구독을 열고 subscription_started을 기다린 후 다른 연결에서 session.snapshot을 요청하는 동안 계속 읽으세요. 신뢰할 수 있는 읽기를 사용하여 현재 상태를 조정합니다. 캐시를 스냅샷으로 교체하고 들어오는 이벤트를 다른 읽기를 트리거하는 무효화 신호로 처리합니다. 읽기가 진행되는 동안 이벤트가 도착하면 새로 고침을 직렬화하고 다시 새로 고칩니다.

스냅샷과 이벤트에는 공유된 시퀀스 경계가 없습니다. 순서는 항목 간이나 스냅샷을 기준으로 하는 것이 아니라 각 구독 항목 내에서 보장되므로 버퍼링된 이벤트 페이로드를 스냅샷에 무조건 재생하지 마세요. 복구는 누락된 이벤트 기록이 아닌 현재 상태를 복원합니다. 또 다른 events_lost를 다시 구독하고 조정해야 합니다. 느린 리더는 읽기 처리량을 늘리거나 이벤트 로드를 줄여야 할 수도 있습니다.

Workspace 이벤트 구독에는 workspace.created, workspace.updated, workspace.metadata_updated, workspace.renamed, workspace.moved, workspace.reordered, workspace.closed 및 workspace.focused이 포함됩니다. workspace.metadata_updated은 플러그인 이벤트 훅를 호출하지 않고 토큰 변경 사항 및 TTL 만료를 보고합니다. 다른 작업 공간 이벤트는 Herdr UI/런타임 수명주기를 설명합니다. workspace.created에는 작업 공간이 작업 트리 그룹에 속할 때 선택적 workspace.worktree 출처가 포함됩니다. workspace.moved에는 이동된 workspace_id, 요청된 insert_index 및 업데이트된 주문된 workspaces 목록이 포함됩니다. workspace.reordered에는 원자적으로 이동된 workspace_ids, 선택적 before_workspace_id 및 신뢰할 수 있는 순서의 workspaces 목록이 포함됩니다. workspace.closed에는 Herdr가 제거하기 전에 식별할 수 있는 최종 workspace 스냅샷이 포함되어 있습니다. 탭 이벤트 구독에는 tab.created, tab.closed, tab.focused, tab.renamed 및 tab.moved가 포함됩니다. tab.moved에는 해당 작업 공간에 대해 이동된 tab_id, workspace_id, 요청된 insert_index 및 업데이트된 정렬된 tabs 목록이 포함됩니다. 패널 이벤트 구독에는 pane.created, pane.updated, pane.closed, pane.focused, pane.moved, pane.exited, pane.agent_detected, pane.output_matched, pane.agent_status_changed 및 pane.scroll_changed이 포함됩니다. pane.focused은 또한 이 서버에 연결된 모든 클라이언트의 수동 패널 선택 변경 사항을 보고합니다. 다른 클라이언트의 보기를 이동하지 않으며 해당 페이로드는 클라이언트를 식별하지 않습니다. 이미 선택한 패널을 선택하면 다시 내보내지지 않습니다. 터미널 제목 변경 사항은 pane.updated을 내보낼 수 있지만 terminal_title_stripped이 변경되지 않은 경우 스피너 전용 원시 제목 변경 사항은 이를 내보내지 않습니다. pane.scroll_changed는 하나의 pane_id로 범위가 지정되며 Herdr가 변경된 스크롤 스냅샷을 관찰할 때마다 pane_id, workspace_id 및 현재 scroll 측정항목을 내보냅니다. 레이아웃 이벤트 구독에는 layout.updated이 포함됩니다. 이벤트는 하나의 탭에 대해 업데이트된 PaneLayoutSnapshot을 전달합니다. session.snapshot으로 캐시를 유지 관리하는 클라이언트는 이 이벤트를 사용하여 신뢰할 수 있는 읽기를 통해 영향을 받는 레이아웃을 새로 고쳐야 합니다. 지연된 페이로드는 최신 스냅샷보다 앞설 수 있습니다.

Worktree 이벤트 구독에는 worktree.created, worktree.opened 및 worktree.removed이 포함됩니다. Worktree 이벤트는 Git 체크아웃 수명 주기를 설명합니다. worktree.created에는 열린 workspace 및 생성된 worktree이 포함됩니다. worktree.opened에는 대상 workspace, 열린 worktree 및 already_open이 포함됩니다. worktree.removed에는 workspace_id이 포함되고 worktree 및 forced이 제거되었습니다.

수명 주기 이벤트에는 events.subscribe을 사용하세요. 일회성 대기가 지원되는 경우 전용 대기 도우미는 별도로 문서화됩니다.

프로토콜 클라이언트를 작성하지 않는 한 CLI를 통해 pane.read을 사용하십시오.

herdr pane read w1:p1 --source visible --lines 80
herdr pane read w1:p1 --source recent --lines 120
herdr pane read w1:p1 --source recent-unwrapped --lines 120
herdr pane read w1:p1 --source detection

recent-unwrapped은 소프트 래핑을 무시하므로 로그에 유용합니다. detection은 에이전트 화면 감지에 사용되는 하단 버퍼 스냅샷을 반환합니다.

대기를 사용하여 에이전트와 스크립트를 조정하세요.

herdr agent wait w1:p1 --until done
herdr agent wait w1:p1 --until blocked

에이전트는 임의의 명령 완료가 아닌 의미 체계 상태를 관찰합니다.

성공적인 응답은 다음과 같습니다.

{
  "id": "req_1",
  "result": {
    "type": "pane_info",
    "pane": {
      "pane_id": "w1:p1",
      "terminal_id": "term_abc123",
      "workspace_id": "w1",
      "tab_id": "w1:t1",
      "focused": true,
      "agent_status": "working",
      "revision": 42
    }
  }
}

server.agent_manifests은 규칙을 다시 로드하지 않고 활성 에이전트 감지 매니페스트 소스 및 원격 업데이트 진단을 반환합니다.

{
  "id": "req_1",
  "result": {
    "type": "agent_manifest_status",
    "last_check_unix": 1781043522,
    "last_result": "checked",
    "manifests": [
      {
        "agent": "cursor",
        "source": "/home/me/.config/herdr/agent-detection/cursor.toml",
        "source_kind": "local override",
        "active_version": "2026.06.10.1",
        "cached_remote_version": "2026.06.10.1",
        "local_override_shadowing_remote": true,
        "remote_update_result": "current"
      }
    ]
  }
}

last_check_unix, last_result, active_version, cached_remote_version, remote_update_result, remote_update_error, remote_last_checked_unix 및 warning과 같은 필드는 사용할 수 없는 경우 생략됩니다. server.reload_agent_manifests은 메모리 내 규칙 캐시를 다시 로드한 후 동일한 manifests 항목 형태로 agent_manifest_reload을 반환합니다.

agent.explain은 서버의 활성 매니페스트 캐시를 사용하여 실행 중인 서버에서 대상 패널의 감지 스냅샷을 평가합니다.

{
  "id": "req_2",
  "method": "agent.explain",
  "params": { "target": "w1:p1" }
}

응답에는 최종 상태, 매니페스트 소스 및 버전, 일치하는 규칙, 평가된 규칙 증거, 상태 건너뛰기 이유, 유휴 대체 이유 및 전체 수명 주기 훅 권한이 화면 규칙을 신뢰할 수 없게 만드는 경우 screen_detection_skip_reason을 포함하여 herdr agent explain --json에서 출력한 동일한 설명 개체가 포함됩니다.

클라이언트에는 agent.explain을 지원하는 실행 중인 서버가 필요합니다. Herdr를 업그레이드한 후 이 방법을 사용하기 전에 서버를 다시 시작하거나 실시간 핸드오프하세요.

오류는 다음과 같습니다.

{
  "id": "req_1",
  "error": {
    "code": "not_found",
    "message": "pane not found"
  }
}

클라이언트가 렌더링한 Herdr UI는 로컬 및 SSH 서버에 대해 안정적인 엔드포인트 생성을 사용합니다. 클라이언트와 서버 빌드는 일치할 필요가 없습니다. 연결 설정 중에 핵심 스냅샷, 화면, 입력 및 Blob 코덱에 동의하고 서버는 지원하는 API 메서드와 선택적 기능을 광고합니다. 저장된 SSH 페더레이션에는 surface_interest 기능이 필요하므로 선택한 시스템만 패널 표면을 스트리밍하고 health_check 기능이 필요하므로 조용히 끊어진 연결이 무기한 온라인 상태를 유지할 수 없습니다. 이 수명 주기 지원이 없는 서버는 명시적으로 업데이트될 때까지 주의 상태를 유지합니다. 다른 누락된 메서드는 해당 작업만 비활성화하고 클라이언트-로컬 알림을 표시합니다. UI 연결을 끊지 않습니다. 거부되거나 시간 초과된 작업도 연결을 종료하지 않고 보고됩니다. 엔드포인트 1세대 이전의 서버에는 최종 업데이트가 한 번 필요합니다.

번호가 매겨진 바이너리 프로토콜은 직접 터미널 연결 및 실시간 핸드오프를 포함하여 동일한 설치 및 내부 작업을 위해 유지됩니다. 다른 빌드에서 해당 작업을 사용하기 전에 ping 또는 herdr status을 확인하세요. JSON API 클라이언트는 알 수 없는 필드를 무시하고 지원되지 않는 메서드를 일반 오류로 처리해야 합니다.