OfferUpBot

OfferUpBot은 외부 에이전트를 위한 OfferUp 실행 레이어입니다. 에이전트는 아이템을 식별하고, 가격을 정하고, 카피를 작성하고, 응답을 결정합니다. OfferUpBot은 OfferUp 접근, 로그인 상태, 지속성, 브라우저 작업, 재시도, 중복 방지, 외부 검증을 처리합니다.

에이전트 지침

대화 기록 없이 작업하는 에이전트는 AGENTS.md에서 시작합니다. 직접적인 OfferUp 실행은 skills/operating-offerupbot/SKILL.md를, 물리적 아이템의 종단 간 소유권은 skills/operating-seller-operator/SKILL.md를, 중대한 이미지 추론은 skills/inspecting-visual-evidence/SKILL.md를 사용합니다. 각 스킬은 태스크가 요구할 때에만 더 깊은 자료를 로드합니다.

런타임 결정

기본 인터페이스는 온디맨드 MCP stdio입니다:

agent launches OfferUpBot
        ↓
MCP tools execute against shared SQLite state and browser profile
        ↓
agent disconnects
        ↓
OfferUpBot exits

상태는 SQLite와 전용 OfferUp 브라우저 프로필에 유지됩니다. 기본 프로세스는 스케줄러, HTTP 수신기, 백그라운드 모니터를 시작하지 않습니다.

연속 monitor 모드는 선택 사항이며 기본적으로 꺼져 있습니다. run:due는 명시적 어니패스(catch-up pass)를 한 번 수행하고 종료합니다.

요구 사항

• 인증된 작업을 위해 Google Chrome이 설치된 macOS

• Node.js 22 이상

• pnpm

Docker, 외부 데이터베이스, Redis, 또는 별도 관리되는 런타임 서비스는 필요하지 않습니다.

설치 및 빌드

git clone https://github.com/yinkev/OfferUpBot.git
cd OfferUpBot
pnpm install
pnpm build

개발용 MCP 진입점을 실행합니다:

pnpm mcp

빌드된 진입점을 실행합니다:

pnpm start

기본 데이터 디렉터리는 다음과 같습니다:

~/.offerupbot/
├── state.sqlite
├── browser-profile/
└── agents.json          # only after restricted agents are created

격리가 필요한 경우 OFFERUPBOT_DATA_DIR로 재정의하세요.

OfferUp 로그인

pnpm auth:login

전용 Chrome 창이 열립니다. 자격 증명은 OfferUp에 직접 입력합니다. OfferUp의 인증 계정 쿼리가 실제 계정 ID를 반환할 때만 로그인이 허용됩니다. 자격 증명은 채팅으로 요청되지 않으며 SQLite에 저장되지 않습니다.

MCP 구성

pnpm build 후 에이전트 호스트를 빌드된 stdio 진입점으로 지정하세요:

{
  "mcpServers": {
    "offerupbot": {
      "command": "node",
      "args": [
        "/absolute/path/to/OfferUpBot/dist/src/index.js"
      ],
      "env": {
        "OFFERUPBOT_DATA_DIR": "/absolute/path/to/.offerupbot"
      }
    }
  }
}

에이전트 토큰이 없으면 로컬 stdio 프로세스는 신뢰된 전체 운영자로 실행됩니다.

에이전트가 더 좁은 권한을 받아야 하는 경우 제한된 신원을 생성하세요:

pnpm agent:create -- \
  --id research-agent \
  --name "Research Agent" \
  --permissions market.read,events.read,watch.manage

변환된 토큰을 해당 에이전트의 MCP 환경에 OFFERUPBOT_AGENT_TOKEN으로 저장하세요. OfferUpBot은 해당 토큰의 SHA-256 해시만 저장합니다.

에이전트 도구

skills/operating-offerupbot/SKILL.md에서 시작하세요; 그 옆의 REFERENCE.md와 WORKFLOWS.md에 상세 계약 및 절차가 있습니다.

판매자 운영자 도구

실행 도구 위에는 물리적 아이템을 종단 간 소유하는 에이전트를 위한 두 번째 MCP 서피스가 있습니다: 30개의 seller.* 도구는 사례/아이템 접수, 사진 및 출처 추적 증거, OCR/결정적 추출 및 정체성 선택, 증거 충분성 확인 질문, 상호 비교 조사, 가격 및 처분 결정, 근거에 기반한 마감 초안 및 검증된 게시/마감, 구매자 분류, 오퍼, 배타적 예약, 약속(충돌 확인 및 멱등적 알림 포함), 만기 할일 운영자 루프, 인계 기록, 삶 주기 분석을 담당합니다.

권한: seller.read(읽기), seller.write(도메인 쓰기; 게시/마감은 추가로 listing.publish/listing.close 필요), seller.communicate(구매자 작업). 메시지는 계속해서 검증된 offerup.send_message를 통해 전달됩니다. skills/operating-seller-operator/SKILL.md에서 시작하세요; 그 옆의 REFERENCE.md와 WORKFLOWS.md에 증거, 시장, 구매자, 수명주기 지침이 있습니다.

ID와 쓰기

OfferUp은 두 가지 구분된 고시 식별자를 사용합니다:

• listing_id: 공개 상세, 대화, 검증, 편집 변형 입력에 사용되는 UUID.

• item_id: /selling, 판매 완료 표시 및 보관 운영에 사용되는 숫로 판매자 재고 ID.

모든 결과 유발 도구에는 지속적인 멱등성 키가 필요합니다. 타임아웃이나 충돌 후 동일한 키를 다시 사용하세요. 키를 변경하면 복구 시도가 중복의 외부 작업으로 변환될 수 있습니다.

명시적 스케줄링 모드

기한이 지난 모든 워치를 한 번 실행하고 종료합니다:

pnpm run:due

연속 폴링이 의도적으로 필요한 경우에만 포그라운드에서 워치 스케줄링을 유지합니다:

pnpm monitor

monitor는 pnpm mcp, pnpm start, 설치, 또는 로그인을 통해서 시작되지 않습니다. 닫으면 연속 폴링이 중단됩니다. 이후 run:due 또는 MCP offerup.run_due 호출은 저장된 워치 상태로부터 따라잡기 실행을 수행합니다.

인계 서피스 (옵트인)

pnpm handoff는 사람 루트 고객과의 접점인 대면 핸드오프를 위한 소규모 포그라운드 전용 HTTP surface를 시작합니다. GET /process/entry에서 기한/대기 중인 핸드오프 카드(구매자, 합의된 가격, 약속, 액세서리, 결함, 결제 정책, 백업 구매자)를 나열하고, GET /api/handoffs를 노출하며, POST /api/handoffs/pass... 및 POST /api/handoffs를 통해 동일한 SQLite 상태에 결과를 기록합니다.

127.0.0.1에 바인딩되어 있고(OFFERUPBOT_HANDOFF_HOST/OFFERUPBOT_HANDOFF_PORT로 변경 가능) OFFERUPBOT_HANDOFF_TOKEN의 전손 토큰이 필요합니다. 미설정인 경우 토큰은 시작 시 생성되어 한 번 출력됩니다. monitor와 마찬가지로 다른 것에 의해 시작되지 않습니다. 기본 런타임은 리스너가 없는 온디맨드 MCP stdio가 유지됩니다.

실패 시맨틱

쓰기는 응답해 있는 verified: true가 포함된 경우에만 완료로 간주됩니다.

중요한 코드:

• OFFERUP_SESSION_EXPIRED / AUTH_REQUIRED: 인증된 작업 전에 OfferUp 로그인을 완료하세요.

• RESOURCE_BUSY: 제어 상태의 계정 또는 브라우저 소속을 다른 프로세스가 점유 중; 같은 멱등성 키로 추후 재시도하세요.

• RESOURCE_LOCK_LOST: 쓰기가 완료되었다고 단정하지 말고 재시도 전에 관련 읽기/동기화 도구를 호출하세요.

• IDEMPOTENCY_CONFLICT: 같은 키로 다른 의도를 제출한 상태; 호출 에이전트의 상태를 조정하세요.

• OFFERUP_FILTER_MISMATCH: OfferUp이 검색 조건을 조용히 무시한 상태; 반환된 집합을 유효한 비교로 사용하지 마세요.

• AUTO_CATEGORY_MISMATCH: OfferUp이 제출된 초안과 다른 카테고리를 적용한 상태.

• CATEGORY_PATH_NOT_TERMINAL: 경로 이상의 상위 카테고리 도달이 아니라 최종 선택 가능한 카테고리에서 멈춘 상태.

검증

일상적인 검증:

pnpm test
pnpm typecheck
pnpm build

설정된 OfferUp 프로필과 공개 사이트에 대한 읽기 전용 실시간 인정 테스트:

OFFERUPBOT_LIVE_TESTS=1 pnpm exec tsx --test \
  tests/account/live.test.ts \
  tests/auth/live.test.ts \
  tests/offerup/public/live.test.ts

안전하게 가로챈 쓰기 계약 인정 테스트:

OFFERUPBOT_LIVE=1 pnpm exec tsx --test --test-concurrency=1 \
  tests/messages/live-direct.test.ts \
  tests/listings/live-browser.test.ts \
  tests/listings/live-close.test.ts

가로챈 테스트는 current 메시지, 목록 게시, 수정, 업로드, 판매 완료, 보관 요청 경로를 라이브 OfferUp UI를 대상으로 실행하면서 중대한 변경의 결과는 로컬에서 충족시킵니다. 실제 리스팅을 생성, 수정, 판매, 보관하지 않습니다.

현재 인정 범위

코드, 공개 읽기, 인증 읽기, 현재 웹 페이지 메시지 변경, 목록 게시/수정 UI 계약, 마감 변경은 구현되어 테스트 과학입니다. 담당 프로세스 내 메모리 에이전트 테스트가 조사에서부터 게시, 받은 편지함, 메시지, 수정, 마감까지 검증합니다.

2026-08-24 일자로 구성된 승인 계정에 대한 실제 리스팅 수명주기: Philips Norelco BG7035/47이 사진 6매로 게시되어 외부 검증되고, $60에서 $55로 수정 및 New 상태가 존속됨을 재검증한 후, 인증 시 상태에서 UNLISTED로 보관되어 확인되었습니다. 이 과정에서 두 가지 실사용 결함이 발견되었고 Fixedam . .

• 외부 앱 목록 대화 상자가 보이는 창에서 최종 카테고리를 선택하는 문제가 있었고, 가격 전용 변경 시 상품의 New 상태를 복구하는 문제가 있었습니다.

(문단 전체에 대한 정확한 지침이므로 앞서 언급한 두 결함 이후 내용 그대로입니다 — 따라서 실제 문서에 이어지는 “남은 실제 메시지 전송 판문”부터 계속합니다.)

나중에 offerup.send_message를 통해 직접 어댑터로 $50 현금 오퍼 하나를 전송하고, 반환된 메시지 ID를 정확한 스레드에서 다시 읽었으며, 인증 인박스 동기화로 대화가 확인되었습니다. 셀러는 나중에 "Its a pokemon center branch"라고 답하며pokemon center 추론 실패를 드러났습니다. 상품의 첫 번째 사진은 Pokemon Center 특별 버전을 분명히 나타내고 있었지만 에이전트는 동일한 ETB로 가치를 매겼습니다. TCGplayer 상세 프로덕 트및 692949는 거의 $120였기 때문에 상기 $50 오라는 정확한 시장가의 약 42%이지, 78%가 아닙니다. 단일 희생자 단위 테스트는 통과했지만 변형 식별, 가치 평가, 목표 선택이 실패했습니다. 수정된 사후 분석은 docs/at/2026-08-24-real-message-send.md에 있습니다.

지정된 실제 전송 게이트들이 모두 완료되었습니다. 다른 실제 쓰기에도 여전히 명시적으로 지정된 목록 또는 대화가 필요합니다. 반복 가능한 회귀 테스트는 계속 인터셉트된 상태로 유지되어 임의의 계정 개체를 변형하지 않아야 합니다.

판매자-운영자 계층 (2026-08 추가)

이 실행 계층 위에 판매자-자 시스템이 있습니다: 표준 물리적 아이템과 출처 추적 증거, 식별자 해석, 거래 완료 대 활성 비교 분리가 있는 시장/가격 조사, 가중 상품 조제, 게이트식 등재 조정, 구매자/오퍼/전용 예약(충돌 확인 및 멱등 알림 포함) 상태, 숫jas 핸드오프 기록, 재구성 가능한 사례 컨텍스트. 프로덕션 런타임에 완전히 연결되어 있으며(가동 시 모든 스키마 보장, runtime.runWhen()이 워치 및 셀러 작업의 승인 캐치업 패스를 실행, 계정 목록 동기화가 views/discussions/price 열을 추가함) 위의 seller.* 도구를 통해 에이전트에 노출됩니다.

선택 사항인 통합 기능, 모두 기본적으로 해제:

• OFFERUPBOT_READ_ON : 1 = 1 — 모든 중대한 OfferUp 쓰기 공개(게시/수정/마감/전송, 번들러 경로 포함)를 차단합니다.

• OFFERUPBOT_EBAY_CLIENT_ID / OFFERUPBOT_EBAY_CLIENT_SECRET — 활성 구매 요청가 + 판매됨, 공개 API) eBay 비교 출처를 활성화합니다. 이 변수 없으면 소스는 불가 상태로 보고며, 결과가 비어 있습니다. 아무것도 스크래핑하지 않습니다.

• OCR은 darwin + osascript + macOS Vision을 사용할 수 있을 때 실행되며, 그 외 환경에서는 결정적 추출로만 동작합니다.

결과 분석(src/analytics)은 판매된 항목과 판매되지 않은 항목 모두에 대해 전체 메트릭 집합을 계산하고, 완료된 결과에서 얻은 카테고리 사전 확률은 가격 결정 및 처분 정책에 피드백됩니다(경계 설정, 표본 크기 축소, 결정 근거에 기록됨). 레이어 맵과 불변 조건은 docs/seller-operator-architecture.md에서, 빌드 상태는 docs/seller-operator-tracker.md에서, 통제된 전체 수명주기 인수 승인(외부 쓰기 모킹 — 실제 마켓플레이스 변형 없음)은 tests/e2e/seller-operator.test.ts에서 확인하세요.