apick-api 3.9.0 → 3.10.0

package/CHANGELOG.md

@@ -1,9 +1,15 @@
-# Changelog
+# 3.10.0 — 2026-10-04
 
-## 3.9.0 — 2026-10-04
+서브에이전트 전용 REST 메서드와 타입을 추가했습니다. 설치형 스킬의 사용량 과금 정보를 제공합니다.
 
-- `getSkillPerformance()`와 공개 성능표 타입을 추가했습니다. 시험 방식·표본 수·평가일·성공률 구간·미검증 상태를 확인할 수 있습니다.
-- Add `getSkillPerformance()` and report types for methods, sample sizes, evaluation dates, success-rate intervals and untested states.
+Adds the Subagent integration and usage-based installed-agent contract. Existing API contracts remain supported.
+
+# Changelog
+
+## 3.9.0 — 2026-10-04
+
+- `getSkillPerformance()`와 공개 성능표 타입을 추가했습니다. 시험 방식·표본 수·평가일·성공률 구간·미검증 상태를 확인할 수 있습니다.
+- Add `getSkillPerformance()` and report types for methods, sample sizes, evaluation dates, success-rate intervals and untested states.
 
 ## 3.8.1 — 2026-10-03
 

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 APICK
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 APICK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -101,8 +101,8 @@ Leave the allowed-IP list blank for unrestricted access. To restrict access, reg
 | `requestHealthCheckup(input)` / `getHealthCheckup(transactionId)` | 국가 건강검진 결과 조회 / National health checkup results | JSON |
 | `requestCashReceiptDeduction(input)` / `getCashReceiptDeduction(transactionId)` | 현금영수증 소득공제 내역 / Cash receipt income deductions | JSON |
 | `requestTaxReturnHistory(input)` / `getTaxReturnHistory(transactionId)` | 국세 신고내역 조회 / National tax return history | JSON |
-| `searchSkills(options)` / `getSkill(skillId)` | Skill 검색·상세 / Search and inspect Skills | JSON |
-| `getSkillPerformance()` | 시험 방법·표본 수·기계 검사·품질 점수 / Measured results and methods | JSON |
+| `searchSkills(options)` / `getSkill(skillId)` | Skill 검색·상세 / Search and inspect Skills | JSON |
+| `getSkillPerformance()` | 시험 방법·표본 수·기계 검사·품질 점수 / Measured results and methods | JSON |
 | `quoteSkill(skillId, input, options)` | Skill 견적(무료) / Quote a run (free) | JSON |
 | `runSkill(skillId, input, options)` | Skill 실행 / Run a Skill | JSON |
 | `getSkillRun(runId)` / `getSkillRunResult(runId)` / `cancelSkillRun(runId)` | 실행 조회·결과·취소 / Read, fetch result, cancel | JSON |
@@ -116,7 +116,7 @@ Search and run reviewed Skills. Points are charged only when a result in the pro
 ```js
 import { randomUUID } from 'node:crypto';
 
-const found = await apick.searchSkills({ query: '상품명', limit: 5 });
+const found = await apick.searchSkills({ query: '상품명', limit: 5 });
 const skillId = found.data.items[0].skill_id;
 const detail = await apick.getSkill(skillId);          // input_schema, output_schema, price_points, estimated_points
 const input = { product_name: '튼튼한 접이식 우산' };
@@ -131,11 +131,11 @@ while (!['succeeded', 'failed', 'timed_out', 'cancelled'].includes(run.status))
 console.log(run.status, run.billing, run.result);
 ```
 
-검증 결과는 [스킬 성능표](https://apick.app/skills/performance) 또는 `const { data } = await apick.getSkillPerformance()`로 확인합니다. 표본 수·시험일·방법·기계 검사 통과율과 모델 평가 점수를 함께 읽으세요. 미검증 값은 `null`이며, 과거의 다른 조건에서 얻은 점수는 `legacy`로 구분합니다. 모델 점수는 객관적 정확도나 판매 성과 보장이 아닙니다.
-
-See the [Skill performance report](https://apick.app/skills/performance) or call `const { data } = await apick.getSkillPerformance()`. Read sample sizes, dates, methods, machine checks and model scores together. Unmeasured values are `null`; historical results under different conditions are in `legacy`. Model scores are not objective accuracy or sales guarantees.
-
-`searchSkills({ sort })` 로 추천(`recommended`)·인기(`popular`)·많이 사용(`used`)·좋아요순(`likes`)·평점순(`rating`)·최신(`new`) 순서를 고르고, 검색·상세 응답의 `usage_label`(사용 건수 구간)·`like_count`·`review_count`·`rating_average` 로 Skill 을 비교할 수 있습니다.
+검증 결과는 [스킬 성능표](https://apick.app/skills/performance) 또는 `const { data } = await apick.getSkillPerformance()`로 확인합니다. 표본 수·시험일·방법·기계 검사 통과율과 모델 평가 점수를 함께 읽으세요. 미검증 값은 `null`이며, 과거의 다른 조건에서 얻은 점수는 `legacy`로 구분합니다. 모델 점수는 객관적 정확도나 판매 성과 보장이 아닙니다.
+
+See the [Skill performance report](https://apick.app/skills/performance) or call `const { data } = await apick.getSkillPerformance()`. Read sample sizes, dates, methods, machine checks and model scores together. Unmeasured values are `null`; historical results under different conditions are in `legacy`. Model scores are not objective accuracy or sales guarantees.
+
+`searchSkills({ sort })` 로 추천(`recommended`)·인기(`popular`)·많이 사용(`used`)·좋아요순(`likes`)·평점순(`rating`)·최신(`new`) 순서를 고르고, 검색·상세 응답의 `usage_label`(사용 건수 구간)·`like_count`·`review_count`·`rating_average` 로 Skill 을 비교할 수 있습니다.
 Pick an order with `searchSkills({ sort })` (`recommended`, `popular`, `used`, `likes`, `rating`, `new`) and compare Skills with `usage_label` (a usage tier), `like_count`, `review_count` and `rating_average` in search and detail responses.
 
 `searchSkills({ sort })` 로 추천(`recommended`)·인기(`popular`)·많이 사용(`used`)·좋아요순(`likes`)·평점순(`rating`)·최신(`new`) 순서를 고르고, 검색·상세 응답의 `usage_label`(사용 건수 구간)·`like_count`·`review_count`·`rating_average` 로 Skill 을 비교할 수 있습니다.
@@ -464,3 +464,18 @@ if (status.data.status === "completed") {
 ### 스킬 결과 파일 / Skill result files
 
 `getSkillArtifact(runId, fileId)` returns authenticated binary artifacts. 가격·시간·호출 수 범위와 다운로드 예제: [스킬 파일 가이드 / guide](docs/skill-artifacts.md).
+
+## 서브에이전트 / Subagent
+
+설치형 `apick-agent` 상품은 `apick-subagent` 스킬 패키지와 전용 REST·MCP를 사용합니다. 원가 +40%, 승인된 동일 결과 캐시 무료, 충전 잔액 외 상품 한도 없음. [연동 가이드](https://apick.app/dev_guide/subagent).
+
+The installed `apick-agent` product uses the `apick-subagent` skill package and dedicated REST/MCP interfaces. Confirmed cost plus 40%; approved identical cache reuse is free, with no product quota beyond prepaid balance. [Integration guide](https://apick.app/dev_guide/subagent).
+
+```sh
+npx -y apick-mcp --server subagent
+# Local workspace collection / 로컬 파일 수집
+npm install -g apick-subagent
+apick-subagent install
+```
+
+Set `APICK_API_KEY` in the environment. 원격 MCP는 업로드된 자료를 처리합니다. The remote MCP processes uploaded content; the installed bridge collects local files.

package/SECURITY.md

@@ -1,11 +1,11 @@
-# Security
-
-## API keys
-
-Keep APICK API keys in server-side environment variables. Do not commit keys, include them in client-side browser bundles, place them in URLs, or print them in logs.
-
-If a key may have been exposed, regenerate it from your APICK account immediately.
-
-## Reporting a vulnerability
-
-Please report security issues privately through the contact channel listed at <https://apick.app>. Do not open a public issue containing credentials, personal data, or exploit details.
+# Security
+
+## API keys
+
+Keep APICK API keys in server-side environment variables. Do not commit keys, include them in client-side browser bundles, place them in URLs, or print them in logs.
+
+If a key may have been exposed, regenerate it from your APICK account immediately.
+
+## Reporting a vulnerability
+
+Please report security issues privately through the contact channel listed at <https://apick.app>. Do not open a public issue containing credentials, personal data, or exploit details.

package/docs/guide.en.md

@@ -1,9 +1,9 @@
 # apick-api English guide
 
-## Skill performance report
-
-Use `const { data } = await apick.getSkillPerformance()` to read the [public measurements](https://apick.app/skills/performance). Review sample sizes, dates, methods and failure reasons together. Model scores are not objective accuracy; unmeasured values are `null`. Reading the report does not execute a paid Skill.
-
+## Skill performance report
+
+Use `const { data } = await apick.getSkillPerformance()` to read the [public measurements](https://apick.app/skills/performance). Review sample sizes, dates, methods and failure reasons together. Model scores are not objective accuracy; unmeasured values are `null`. Reading the report does not execute a paid Skill.
+
 ## Request and response formats
 
 All SDK requests with a body use `multipart/form-data`. Arrays use separate indexed fields such as `utterance_ids[0]`; let the SDK set the Content-Type boundary. GET requests have no body. The server continues accepting older JSON requests for compatibility.

package/docs/guide.ko.md

@@ -1,9 +1,9 @@
 # apick-api 한국어 가이드
 
-## 스킬 성능표
-
-`const { data } = await apick.getSkillPerformance()`로 [공개 측정표](https://apick.app/skills/performance)를 조회합니다. 표본 수·시험일·검사 방법·실패 사유를 함께 확인하세요. 모델 점수는 객관적 정확도가 아니며 미검증 값은 `null`입니다. 조회 자체에는 유료 실행이 필요하지 않습니다.
-
+## 스킬 성능표
+
+`const { data } = await apick.getSkillPerformance()`로 [공개 측정표](https://apick.app/skills/performance)를 조회합니다. 표본 수·시험일·검사 방법·실패 사유를 함께 확인하세요. 모델 점수는 객관적 정확도가 아니며 미검증 값은 `null`입니다. 조회 자체에는 유료 실행이 필요하지 않습니다.
+
 ## 요청과 응답 형식
 
 SDK의 본문 요청은 모두 `multipart/form-data`입니다. `utterance_ids[0]`처럼 배열을 개별 필드로 전송하며 `Content-Type` 헤더를 직접 지정할 필요가 없습니다. GET 조회는 본문을 보내지 않습니다. 기존 JSON 요청도 서버에서 호환용으로 계속 처리합니다.

package/docs/subagent.md

@@ -0,0 +1,39 @@
+# 서브에이전트 / Subagent
+
+`apick-agent`는 설치형 상품이며 `quoteSkill`·`runSkill` 대신 전용 API를 사용합니다. 성공 작업의 확인된 원가에 40%를 가산하며 승인된 동일 결과 캐시는 무료입니다. 충전 잔액 외 상품 사용량 한도는 없습니다.
+
+`apick-agent` is an installed-agent product. Use the dedicated API rather than `quoteSkill` or `runSkill`. Successful work is billed at confirmed model cost plus 40%; approved identical-result cache reuse is free. There are no product usage quotas beyond prepaid balance.
+
+```js
+import { ApickClient } from 'apick-api';
+import { createHash } from 'node:crypto';
+const api = new ApickClient({ apiKey: process.env.APICK_API_KEY });
+const bytes = Buffer.from('검토할 공개 문서입니다.');
+const file = await api.createSubagentFile({
+  path: 'docs/sample.txt', bytes: bytes.length,
+  sha256: createHash('sha256').update(bytes).digest('hex'), retention: 'seven_days'
+});
+if (file.data.state !== 'ready') {
+  for (let offset = 0; offset < bytes.length; offset += file.data.part_bytes) {
+    await api.uploadSubagentPart(file.data.file_id, offset / file.data.part_bytes,
+      bytes.subarray(offset, offset + file.data.part_bytes).toString('base64'));
+  }
+  await api.completeSubagentFile(file.data.file_id);
+}
+const job = await api.dispatchSubagent({kind:'summarize', goal:'핵심 내용과 근거를 정리하세요',
+  file_ids:[file.data.file_id]}, {idempotencyKey:'sample-summary-20261004-001'});
+const result = await api.collectSubagent(job.data.job_id);
+// 완료 후 evidence_ids를 조회하여 인용·해시를 직접 검토하세요.
+// Once complete, fetch evidence_ids and independently review quotes and hashes.
+console.log(result.data.state);
+```
+
+접수 응답은 작업 ID를 신속히 반환합니다. 같은 멱등 키와 같은 내용은 기존 작업을 반환하며 내용이 다르면 409입니다. 연결 종료는 취소가 아닙니다. `cancelSubagent`로 명시적으로 취소하세요. `retention:'none'`은 검수 완료 후 삭제하고 임시 보관은 최대 1시간입니다.
+
+Submission returns a job ID promptly. Replay the same idempotency key and payload after response loss; a changed payload conflicts with HTTP 409. Disconnecting does not cancel work; use `cancelSubagent`. `retention:'none'` deletes after review, with temporary retention capped at one hour.
+
+`subagentUsage`는 호출·토큰·예약·청구·해제·캐시·전송 지표를 반환합니다. 캐시 예상 회피 비용은 동일 작업의 최초 계산 비용 기준이며 주 모델의 실제 청구 절감액이 아닙니다.
+
+`subagentUsage` returns calls, tokens, reservations, charges, releases, cache and transfer metrics. Estimated avoided cache cost uses the original job's calculated cost and is not a measured reduction in the main model's bill.
+
+[전체 REST·MCP 가이드 / Full guide](https://apick.app/dev_guide/subagent)

package/package.json

@@ -1,71 +1,71 @@
-{
-  "name": "apick-api",
-  "version": "3.9.0",
-  "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
-  "type": "module",
-  "main": "./src/index.cjs",
-  "module": "./src/index.js",
-  "types": "./src/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./src/index.d.ts",
-      "import": "./src/index.js",
-      "require": "./src/index.cjs"
-    }
-  },
-  "files": [
-    "src",
-    "docs",
-    "examples",
-    "README.md",
-    "CHANGELOG.md",
-    "SECURITY.md",
-    "LICENSE"
-  ],
-  "sideEffects": false,
-  "engines": {
-    "node": ">=18"
-  },
-  "scripts": {
-    "test": "node --test && npm run test:types",
-    "test:types": "tsc -p tsconfig.json",
-    "test:coverage": "node --test --experimental-test-coverage",
-    "prepublishOnly": "npm test"
-  },
-  "devDependencies": {
-    "typescript": "^7.0.2"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/lead788/apick-api.git"
-  },
-  "bugs": {
-    "url": "https://github.com/lead788/apick-api/issues"
-  },
-  "homepage": "https://apick.app/dev_guide",
-  "license": "MIT",
-  "author": "APICK",
-  "publishConfig": {
-    "access": "public",
-    "provenance": false
-  },
-  "keywords": [
-    "apick",
-    "api",
-    "sdk",
-    "korea",
-    "korean-api",
-    "business-registry",
-    "parcel-tracking",
-    "address",
-    "ocr",
-    "whois",
-    "dns",
-    "google-search",
-    "pdf",
-    "excel",
-    "tts-jobs",
-    "text-summary",
-    "image-generation"
-  ]
-}
+{
+  "name": "apick-api",
+  "version": "3.10.0",
+  "description": "Official zero-dependency Node.js client for APICK data, AI, and image APIs. 에이픽 데이터·AI·이미지 API 공식 Node.js SDK.",
+  "type": "module",
+  "main": "./src/index.cjs",
+  "module": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.ts",
+      "import": "./src/index.js",
+      "require": "./src/index.cjs"
+    }
+  },
+  "files": [
+    "src",
+    "docs",
+    "examples",
+    "README.md",
+    "CHANGELOG.md",
+    "SECURITY.md",
+    "LICENSE"
+  ],
+  "sideEffects": false,
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test && npm run test:types",
+    "test:types": "tsc -p tsconfig.json",
+    "test:coverage": "node --test --experimental-test-coverage",
+    "prepublishOnly": "npm test"
+  },
+  "devDependencies": {
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lead788/apick-api.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lead788/apick-api/issues"
+  },
+  "homepage": "https://apick.app/dev_guide",
+  "license": "MIT",
+  "author": "APICK",
+  "publishConfig": {
+    "access": "public",
+    "provenance": false
+  },
+  "keywords": [
+    "apick",
+    "api",
+    "sdk",
+    "korea",
+    "korean-api",
+    "business-registry",
+    "parcel-tracking",
+    "address",
+    "ocr",
+    "whois",
+    "dns",
+    "google-search",
+    "pdf",
+    "excel",
+    "tts-jobs",
+    "text-summary",
+    "image-generation"
+  ]
+}

package/src/index.cjs

@@ -63,7 +63,8 @@ const SERVICES = Object.freeze(Object.fromEntries(
 	])
 ));
 
-function redact(value, apiKey) {
+function normalizeSubagentId(value,prefix){if(typeof value!=='string'||!new RegExp('^'+prefix+'_[a-f0-9]{32}$').test(value))throw new TypeError('Invalid subagent identifier.');return value;}
+function redact(value, apiKey) {
 	let text = String(value || '');
 	if (apiKey) text = text.split(apiKey).join('***');
 	return text.replace(/(Authorization\s*:\s*Bearer\s*)\S+/gi, '$1***').replace(/(CL_AUTH_KEY\s*[:=]\s*)\S+/gi, '$1***');
@@ -949,10 +950,25 @@ class ApickClient {
 	}
 
 	getSkillPerformance() {
-		return this._skills('GET', '/skills/performance/data.json');
+		return this._skills('GET', '/skills/performance/data.json');
 	}
 
-	getSkill(skillId) {
+	_subagent(method, route, options) { return this._skills(method, '/rest/subagent/v1' + route, options); }
+	subagentStatus() { return this._subagent('GET', '/status'); }
+	subagentUsage() { return this._subagent('GET', '/usage'); }
+	createSubagentFile(input) { return this._subagent('POST', '/files', {body: input}); }
+	getSubagentFile(fileId) { return this._subagent('GET', '/files/' + normalizeSubagentId(fileId,'saf')); }
+	uploadSubagentPart(fileId, partNo, data) { if(!Number.isSafeInteger(partNo)||partNo<0||typeof data!=='string')throw new TypeError('Invalid upload part.');return this._subagent('POST','/files/'+normalizeSubagentId(fileId,'saf')+'/parts',{body:{part_no:partNo,data}}); }
+	completeSubagentFile(fileId) { return this._subagent('POST','/files/'+normalizeSubagentId(fileId,'saf')+'/complete',{body:{}}); }
+	deleteSubagentFile(fileId) { return this._subagent('DELETE','/files/'+normalizeSubagentId(fileId,'saf')); }
+	dispatchSubagent(input, options) { const key=requiredString('idempotencyKey',options?.idempotencyKey,200);if(key.length<8)throw new TypeError('idempotencyKey must contain at least 8 characters.');return this._subagent('POST','/jobs',{body:input,idempotencyKey:key}); }
+	collectSubagent(jobId, options) { return this._subagent('GET','/jobs/'+normalizeSubagentId(jobId,'saj'),{query:options?.cursor?{cursor:String(options.cursor)}:{}}); }
+	subagentEvidence(jobId,evidenceIds) { return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/evidence',{body:{evidence_ids:evidenceIds}}); }
+	reviewSubagent(jobId,resultHash,decision) { if(!['accepted','rejected'].includes(decision)||!/^[a-f0-9]{64}$/.test(resultHash))throw new TypeError('Invalid review.');return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/review',{body:{result_hash:resultHash,decision}}); }
+	cancelSubagent(jobId) { return this._subagent('POST','/jobs/'+normalizeSubagentId(jobId,'saj')+'/cancel',{body:{}}); }
+	deleteSubagentJob(jobId) { return this._subagent('DELETE','/jobs/'+normalizeSubagentId(jobId,'saj')); }
+
+	getSkill(skillId) {
 		return this._skills('GET', '/rest/skills/' + normalizeSkillId(skillId));
 	}
 

package/src/index.d.ts

@@ -323,9 +323,22 @@ export class ApickClient {
 	getCashReceiptDeduction(transactionId: string): Promise<ApickResult<DataRequestResult<CashReceiptDeductionResultPayload>>>;
 	requestTaxReturnHistory(input: RequestTaxReturnHistoryInput): Promise<ApickResult<DataRequestAcceptedData>>;
 	getTaxReturnHistory(transactionId: string): Promise<ApickResult<DataRequestResult<TaxReturnHistoryResultPayload>>>;
-	searchSkills(options?: SkillSearchOptions): Promise<ApickResult<SkillPage<SkillSummary>>>;
-	/** Public measured results and methods; model scores are not accuracy guarantees. */
+	searchSkills(options?: SkillSearchOptions): Promise<ApickResult<SkillPage<SkillSummary>>>;
+	/** Public measured results and methods; model scores are not accuracy guarantees. */
 	getSkillPerformance(): Promise<ApickResult<SkillPerformanceReport>>;
+	subagentStatus(): Promise<ApickResult<Record<string, unknown>>>;
+	subagentUsage(): Promise<ApickResult<Record<string, unknown>>>;
+	createSubagentFile(input: {path:string;bytes:number;sha256:string;retention?:'seven_days'|'none'}): Promise<ApickResult<SubagentFile>>;
+	getSubagentFile(fileId:string): Promise<ApickResult<SubagentFile>>;
+	uploadSubagentPart(fileId:string,partNo:number,data:string): Promise<ApickResult<Record<string,unknown>>>;
+	completeSubagentFile(fileId:string): Promise<ApickResult<SubagentFile>>;
+	deleteSubagentFile(fileId:string): Promise<ApickResult<Record<string,unknown>>>;
+	dispatchSubagent(input:SubagentTask,options:{idempotencyKey:string}): Promise<ApickResult<SubagentJob>>;
+	collectSubagent(jobId:string,options?:{cursor?:string}): Promise<ApickResult<SubagentJob>>;
+	subagentEvidence(jobId:string,evidenceIds:string[]): Promise<ApickResult<Record<string,unknown>>>;
+	reviewSubagent(jobId:string,resultHash:string,decision:'accepted'|'rejected'): Promise<ApickResult<Record<string,unknown>>>;
+	cancelSubagent(jobId:string): Promise<ApickResult<SubagentJob>>;
+	deleteSubagentJob(jobId:string): Promise<ApickResult<Record<string,unknown>>>;
 	getSkill(skillId: string): Promise<ApickResult<SkillDetail>>;
 	quoteSkill(skillId: string, input: Record<string, unknown>, options?: { version?: string }): Promise<ApickResult<SkillQuote>>;
 	runSkill<T = Record<string, unknown>>(skillId: string, input: Record<string, unknown>, options: SkillRunOptions): Promise<ApickResult<SkillRun<T>>>;
@@ -341,38 +354,38 @@ export const SKILL_CATEGORIES: readonly ['data', 'ai', 'dev', 'document', 'marke
 export type SkillCategory = typeof SKILL_CATEGORIES[number];
 /** 검색 순서. 생략하면 등록 순서 / search order; registration order when omitted */
 export const SKILL_SORTS: readonly ['recommended', 'popular', 'used', 'likes', 'rating', 'new', 'mine', 'liked'];
-export type SkillSort = typeof SKILL_SORTS[number];
-export interface SkillPerformanceRate {
-	passed: number; total: number; percent: number; interval95: [number, number];
-}
-export interface SkillPerformanceReport {
-	schema_version: 1;
-	updated_at: string;
-	inventory_verified: boolean;
-	method: { minimum_cases: number; min_score: number; mean_score: number; min_improvement: number; critical_failures: number; description: string; limitations: string[]; interval_note: string; split: { normal: number; boundary: number; adversarial: number } };
-	calibration: { at: string; cases: number; true_positive: number; false_negative: number; false_positive: number; true_negative: number; automatic_release_allowed: boolean } | null;
-	additional_calibrations: Array<{ label: string; at: string; cases: number; detected: number; missed: number; false_positive: number; uncertain: number; automatic_release_allowed: boolean; scope: string }>;
-	skills: Array<{
-		key: string; title: string; group: string; origin: 'new' | 'existing'; published: boolean | null; url: string | null;
-		current: {
-			state: 'not_tested' | 'partial' | 'held' | 'passed' | 'stale'; at?: string;
-			cases: number; planned_cases: number; score: number | null; baseline_score: number | null;
-			score_samples?: number; evaluation_errors?: number;
-			delivery: SkillPerformanceRate | null; machine: SkillPerformanceRate | null;
-			median_seconds: number | null; p95_seconds: number | null; timing_samples?: number;
-			reasons: string[]; method?: string; sample_type?: string;
-			baseline_format_valid?: boolean;
-			evaluation_stage?: 'preliminary' | 'holdout';
-			dataset_composition?: { normal: number; boundary: number; adversarial: number; misplaced_rejections: number; valid: boolean };
-			min_score?: number | null; critical_cases?: number | null;
-			case_split?: { standard: number; boundary: number; adversarial: number };
-			extra_checks?: Array<{ name: string; passed: number; total: number }>;
-			tool_calls?: Array<{ label: string; samples: number; total: number | null; median: number | null; p95: number | null }>;
-			case_results?: Array<{ index: number; name: string; kind: 'standard' | 'boundary' | 'adversarial'; status: 'tested' | 'evaluation_error' | 'machine_only' | 'not_tested'; expected: 'success' | 'reject' | null; machine_pass: boolean; score: number | null; baseline_score: number | null; failed_checks: string[]; reason: string | null }>;
-		};
-		legacy: { cases: number; score: number; baseline_score: number; method: string; independent_holdout: false; at?: string } | null;
-	}>;
-}
+export type SkillSort = typeof SKILL_SORTS[number];
+export interface SkillPerformanceRate {
+	passed: number; total: number; percent: number; interval95: [number, number];
+}
+export interface SkillPerformanceReport {
+	schema_version: 1;
+	updated_at: string;
+	inventory_verified: boolean;
+	method: { minimum_cases: number; min_score: number; mean_score: number; min_improvement: number; critical_failures: number; description: string; limitations: string[]; interval_note: string; split: { normal: number; boundary: number; adversarial: number } };
+	calibration: { at: string; cases: number; true_positive: number; false_negative: number; false_positive: number; true_negative: number; automatic_release_allowed: boolean } | null;
+	additional_calibrations: Array<{ label: string; at: string; cases: number; detected: number; missed: number; false_positive: number; uncertain: number; automatic_release_allowed: boolean; scope: string }>;
+	skills: Array<{
+		key: string; title: string; group: string; origin: 'new' | 'existing'; published: boolean | null; url: string | null;
+		current: {
+			state: 'not_tested' | 'partial' | 'held' | 'passed' | 'stale'; at?: string;
+			cases: number; planned_cases: number; score: number | null; baseline_score: number | null;
+			score_samples?: number; evaluation_errors?: number;
+			delivery: SkillPerformanceRate | null; machine: SkillPerformanceRate | null;
+			median_seconds: number | null; p95_seconds: number | null; timing_samples?: number;
+			reasons: string[]; method?: string; sample_type?: string;
+			baseline_format_valid?: boolean;
+			evaluation_stage?: 'preliminary' | 'holdout';
+			dataset_composition?: { normal: number; boundary: number; adversarial: number; misplaced_rejections: number; valid: boolean };
+			min_score?: number | null; critical_cases?: number | null;
+			case_split?: { standard: number; boundary: number; adversarial: number };
+			extra_checks?: Array<{ name: string; passed: number; total: number }>;
+			tool_calls?: Array<{ label: string; samples: number; total: number | null; median: number | null; p95: number | null }>;
+			case_results?: Array<{ index: number; name: string; kind: 'standard' | 'boundary' | 'adversarial'; status: 'tested' | 'evaluation_error' | 'machine_only' | 'not_tested'; expected: 'success' | 'reject' | null; machine_pass: boolean; score: number | null; baseline_score: number | null; failed_checks: string[]; reason: string | null }>;
+		};
+		legacy: { cases: number; score: number; baseline_score: number; method: string; independent_holdout: false; at?: string } | null;
+	}>;
+}
 export type SkillRunStatus = 'queued' | 'running' | 'completing' | 'succeeded' | 'failed' | 'timed_out' | 'cancelled';
 export type SkillBillingStatus = 'reserved' | 'captured' | 'released' | 'partially_refunded' | 'refunded';
 export type SkillFailureCode = 'EXECUTION_FAILED' | 'OUTPUT_INVALID' | 'TIMED_OUT' | 'CANCELLED' | 'UPSTREAM_UNAVAILABLE';
@@ -408,7 +421,7 @@ export interface SkillSummary {
 	/** 실행마다 같은 기본 금액 / base amount charged on every run */
 	price_points: number;
 	/** 사용량까지 더한 예상 금액 / estimated amount including usage */
-	estimated_points: number;
+	estimated_points: number | null;
 	/** true 면 실행마다 실제 사용량만큼 금액이 달라집니다 / amount varies per run with actual usage */
 	usage_priced: boolean;
 	seller: { name: string }; uses_generative_ai: boolean;
@@ -420,7 +433,9 @@ export interface SkillSummary {
 	rating_average: number | null;
 }
 export interface SkillDetail extends SkillSummary {
-	description: string; billing_rule: 'validated_result'; limits: SkillLimits;
+	description: string; billing_rule: 'validated_result' | 'subagent_usage'; limits: SkillLimits | null;
+	delivery?: 'installed_agent'; installation?: {package:string;command:string;api_key_env:string;guide:string;usage:string};
+	billing?: {markup_percent:number;installation_points:number;base_points:number;complete_cache_points:number;quota:null};
 	input_schema: Record<string, unknown>; output_schema: Record<string, unknown>;
 	examples: unknown[]; stats: Record<string, unknown> | null; published_at: string | null;
 }
@@ -480,3 +495,7 @@ export interface VideoJobData {
 	result_expires_at?: string | null; idempotent_replay?: boolean;
 	error?: { code: string; message: string };
 }
+
+export interface SubagentTask { kind:'inventory'|'extract'|'summarize'|'compare';goal:string;file_ids:string[];focus?:string[];acceptance?:string[];retention?:'seven_days'|'none'; }
+export interface SubagentFile { file_id:string;path:string;sha256:string;bytes:number;state:string;expires_at:string;part_bytes?:number; }
+export interface SubagentJob { job_id:string;kind:SubagentTask['kind'];state:string;billing_state:string;cache_hit:boolean;reserved_points:number;charged_points:number;accrued_points:string;result_hash?:string;result?:Record<string,unknown>; }