aipctl 2026.10.3 → 2026.10.4

package/docs/api-contract-inventory.md

@@ -67,6 +67,53 @@
 | TUNNEL-01 | tunnel | `aipctl admin tunnel status`; `config`/`token` remain gated | `getTunnelStatus`; candidate `getTunnelConfig`, `createTunnelToken` | api | `GET`; candidate `GET`/`POST` | status `/api/cli/v1/organizations/{organizationSlug}/admin/tunnel/status`; candidates retain Web `/config`/`/token` | none | status `{ connected: boolean }` only | status `resource/oas/modules/backend/cli/openapi.yaml`; candidates Tunnel OAS | `backend/api/.../cli/generated/api/CliTunnelApi.kt#getCliTunnelStatus` | `generated-ready` | N/A | `migrate` | none for status; existing personal Tunnel service checks current user/org; token/config secret gates remain | `AI-6344`; sensitive gate `AI-6380` | status contract/adapter/registry tests; actual CLI + Go Tunnel server disconnected/Redis session connected/user isolation, token count unchanged; actual edge handshake not verified |
 | P1-PRESET-01 | preset | `aipctl admin preset list`, `get`, `create`, `update`, `rename`, `delete`, `set-default`, `unset-default`; key rotation commands remain gated | `listPresets`, `getPreset`, `createPreset`, `updatePreset`, `renamePreset`, `deletePreset`, `setPresetAsDefault`, `unsetPresetAsDefault` | api | list/get `GET`; create `POST`; update/default set `PUT`; rename `PATCH`; delete/default unset `DELETE` | `/api/cli/v1/organizations/{organizationSlug}/admin/presets`; `/{presetId}`; `/{presetId}/default` | bounded one-based page/pageSize 1..100; default pageSize 100; existing basic mutation bodies, explicit org in path | dedicated safe `CliPreset` metadata; no installation/json commands, auth, keys or MCP URL; list CLI JSON remains a page array; delete `void` | `resource/oas/modules/backend/cli/openapi.yaml` | `backend/api/.../cli/generated/api/CliPresetApi.kt`; `CliPreset` DTOs | `generated-ready` | `P1` | `migrate` | none for basic operations; user-owned resources require member+owner+org checks despite admin namespace; read service does not mint keys/enrich remotely; domain mutation/audit reused | `AI-6344`; key gate `AI-6380`; larger workload gate `AI-6413` | `src/core/remaining-direct-contract.test.ts`, Backend safe-read/controller tests, registry/manifest/help, trailing argv tests; actual production CLI eight-operation lifecycle, ownership/accessible integration/pagination/quota/key-count/DB/audit checks |
 
+## 본인 quota 진단 계약
+
+`quota status [--org <slug>] [--json]`은 `ApiService.getMyCliQuota`에서
+`GET /api/cli/v1/organizations/{organizationSlug}/quota`를 한 번 호출한다.
+Source OAS는 `resource/oas/modules/backend/cli/paths/v1_quota.yaml`, generated owner는
+`CliQuotaApi#getCliMyQuota`, CLI parser는 `src/core/quota-contract.ts`다.
+Canonical operation은 `cli.quota.self.read`, capability는 `cli.quota.self`, quota class는
+`control-read`다. 현재 인증 actor·active membership을 정책/사용량 조회보다 먼저 검증한다.
+Gateway capability discovery와 동일한 user-global control-read bucket을 쓰며 workload policy
+조회나 metadata/text quota 소진에 의존하지 않는다. bucket은 유한하고 Redis 장애 시 503이다.
+
+응답은 `userLimits`, `organizationSharedLimits`, nullable 정책 version 2개, `usage`만 허용한다.
+UTC 일일 text admissions, 미반납 active, unresolved 수는 PostgreSQL authoritative snapshot이다.
+정책 row가 없으면 version을 `null`로 포함한다. 사용량 실패는 `UNAVAILABLE`과 required-null
+사용량/reset 필드로 표시한다. 본인 사용량과 조직 공유 정책 수치는 반환하지만 조직 aggregate
+사용량·다른 사용자·raw policy·credit 잔액을 반환하지 않는다. HTTP 응답은 `Cache-Control: no-store`다.
+조회는 용량을 예약하거나 기존 permit을 반환하지 않는다. 테스트는 Backend
+`CliQuotaApiControllerTest`, Gateway admission/registry, CLI quota parser/command/API tests다.
+Source OAS의 429/503은 JSON `CliQuotaErrorResponse`와 공유 `CliQuotaErrorDetails`를 선언하며,
+200의 `Cache-Control: no-store`와 429의 조건부 positive-integer `Retry-After`도 포함한다.
+
+## 공통 CLI HTTP 수명과 작업량 상한
+
+`src/core/http-request.ts`가 로컬 admission, fetch, 전체 body 소비를 하나의 deadline으로 묶는다.
+일반 API는 120초·decoded 8 MiB, OAuth는 30초·8 MiB, transfer/export download는 600초·128 MiB,
+external upload는 600초·응답 8 MiB, text execution은 서버 최대 600초에 응답 여유 10초를 더한다.
+Content-Length 사전 검사와 chunked byte 검사를 모두 적용한다. 로컬 lease는 headers 뒤에도
+body 소비 종료까지 유지하고 timeout/cancel/실패 시 해당 lease만 반납한다. deadline 뒤 늦게
+획득된 lease도 요청을 전송하지 않고 반납한다.
+Forced runtime teardown은 interrupt된 HTTP와 늦은 admission cleanup을 최대 5초 기다린 뒤 종료한다.
+
+Mutation transport/invalid-body/timeout 실패는 전송 전 `not-dispatched`, 전송 후 `unknown`;
+GET/HEAD 실패는 `read-failed`다. 알려진 server rejection은 기존 code/status를 유지한다.
+변경·유료 요청의 자동 retry나 legacy fallback은 없다. 개발 Agent stream의 terminal-envelope-only
+구독 재조회는 전체 600초·최대 3회로 제한하며 start/provider 요청은 재실행하지 않는다.
+OAuth registration·authorization-code·refresh POST의 timeout/invalid JSON/잘못된 성공 payload도
+`unknown`과 safe request ID를 로그인·갱신의 최종 오류 경계까지 전달한다. 인증 상태를 확인한 뒤
+재시도하도록 안내하며 자동 재전송 또는 결과가 불명인 응답으로 자격 증명 저장/삭제를 하지 않는다.
+확인된 `invalid_grant`/401 응답은 기존 session-expired 처리로 구분한다.
+Ctrl+C는 보수적인 `CLI_COMMAND_INTERRUPTED`, `outcome=unknown`, exit 130을 출력하며 remote
+rollback을 의미하지 않는다. API/auth/org 실패는 exit 1이고 `--json` stderr에 한 건만 기록한다.
+
+Agent templates 전체 collector는 100페이지·10,000항목·합계 8 MiB·120초를 공유한다.
+반복 ID, total/pageSize 변경, 빈/짧은 중간 페이지와 상한 초과는 오류로 종료하며 부분 성공을
+반환하지 않는다. Snapshot cursor가 없는 동안 같은 크기의 동시 교체까지 검출한다고 보장하지
+않는다. DB/query·다른 endpoint pagination 및 대규모 tenant 측정은 AI-6413에 남아 있다.
+
 ## 공통 CLI request quota 오류 계약
 
 `GA-DIRECT` 업무 호출과 명시적 discovery/진단용 `GET /api/cli/v1/capabilities`는 각각 Gateway request-rate admission을 통과한다. production CLI는 업무마다 capability를 선조회하지 않는다. 로컬 release manifest는 artifact에 없는 명령을 차단하고, 실제 업무 endpoint의 Gateway registry가 최신 server release/rollout/quota를 authoritative하게 검사한다. Gateway-owned source 계약은 `resource/oas/modules/backend-gateway/me/components/schemas/CliQuotaErrorResponse.yaml`과 `CliQuotaErrorDetails.yaml`이다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aipctl",
-  "version": "2026.10.3",
+  "version": "2026.10.4",
   "description": "QueryPie AIP and MCP CLI tool",
   "author": "QueryPie",
   "license": "UNLICENSED",
@@ -22,8 +22,8 @@
     "node": ">=24.18.0"
   },
   "metadata": {
-    "contentHash": "cd3e1d96a6c80cca1c9594573468ecac8876ea644f388d0d53950cc063451a72",
-    "wrapperHash": "1f9932e5f826496deb9203873e0e543319d84afda6610a78305ffa034fd665c0",
+    "contentHash": "4411480e1c3e2e20349fbe7f87334b5ea564727941d33906ebcab631581607e3",
+    "wrapperHash": "b4efb580c4b910212b9ba7cce836f4d6d371cfa79ab494147c7ffe2c67f1fd6e",
     "nativeHash": "006b08c3e391f4571d9b7c0f12d684fe2448106259e7e0581b10f9be362452e9"
   },
   "optionalDependencies": {