app-ai-wiring

앱 ↔ AI 연결 배선 (tiguclaw)

앱에 AI 를 붙이는 방법은 두 가지다. 성격이 완전히 달라 먼저 고르고 배선한다. 사용자가 지정했으면 그대로 따르고, 안 정했으면 §1 로 추천 + 확인받는다(맘대로 정하지 말 것).

§1 어느 쪽인가 — 판단 기준

A 를 고르는 신호: "내 파일 읽어서", "메모리 참고해서", "스킬 태워서", "프로젝트 맥락 알고", 여러 단계 자율 작업, tiguclaw 만의 능력이 핵심일 때. B 를 고르는 신호: 요약·분류·번역·챗봇 등 모델만 있으면 되는 일, 나중에 상용 API 로 갈아탈 계획, 이미 OpenAI SDK 로 짠 앱, 함수호출/비전 같은 표준 기능이 필요할 때.

애매하면 B(표준이라 나중에 A 로 못 바꾸는 손해가 없고, 스왑 자유). 단 "비서를 부르고 싶은 것"이면 B 로는 절대 안 되니 A.

§2 모드 A — tiguclaw 직결 커스텀 엔드포인트

엔드포인트 = 슬래시 명령의 HTTP 판. <home>/endpoints/<name>.md(frontmatter + 프롬프트 템플릿)를 http-bridge 가 매 요청 발견해 서빙한다. 임의 코드 0 = 데이터만, 재시작 불요.

배선

1. register_endpoint 도구로 등록(list_endpoints/delete_endpoint 로 조회·삭제).
   • path — 라우트(예 /weather). 슬래시 시작·소문자 정규화.
   • method — GET|POST(기본 POST).
   • role — 인증 게이트(기본 write). 앱은 bridge 토큰으로 호출.
   • mode — 기본 restricted(도구 0). 비서 도구가 필요하면 명시적으로 열어야 함.
   • 본문 = 프롬프트 템플릿(요청 파라미터를 끼워 넣음).
2. 앱은 그 경로를 호출: POST http://127.0.0.1:<HTTP_BRIDGE_PORT>/<path> + bridge 토큰.

동기 / 스트리밍

엔드포인트도 둘 다 된다 — 앱이 고른다.

• 동기(기본): 그냥 POST → { "result": "<본문>" } 한 번에. 앱 코드 2줄.
• 스트리밍: body 에 "stream": true(또는 ?stream=1) → SSE.

  data: {"type":"delta","text":"…"}    진행 조각(0회 이상)
  data: {"type":"result","result":"…"}  최종(성공 시 1회)
  data: {"type":"error","error":"…"}    실패(1회)
  data: [DONE]                           종료 표식
  

  ★앱은 result/error 를 받았는지로 성패를 판정할 것(연결만 끊긴 것과 구분). ★EventSource 는 POST 불가 → fetch + ReadableStream 으로 읽는다.
• 타임아웃: 엔드포인트 전용 ENDPOINT_TIMEOUT_MS(기본 5분, env 조정). 폴백 낀 긴 턴(70초)이 504로 잘리던 실사고 때문에 분리·상향했다. 스트리밍이면 데이터가 흘러 중간 계층(프록시·Tailscale) idle timeout 도 회피된다.