@polydeukes/adapter-claude-code 0.6.0 → 0.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (3) hide show
  1. package/README.ko.md +41 -40
  2. package/README.md +41 -55
  3. package/package.json +3 -3
package/README.ko.md CHANGED
@@ -1,40 +1,41 @@
1
- # @polydeukes/adapter-claude-code
2
-
3
- **한국어** · [English](./README.md)
4
-
5
- > Claude Code 어휘가 번역되어 사라지는 경계입니다. PreToolUse 페이로드는 코어에 닿기 전에 에이전트 중립적인 약속(covenant) 입력 IR로 바뀝니다.
6
-
7
- **알파(alpha) 단계입니다.** 에이전트와 도구의 리터럴은 의도적으로 이 패키지 안에만 삽니다. 이 패키지가 존재하는 이유가 그 리터럴이 코어에 닿지 않게 하는 것이고,
8
- 그래서 코어의 에이전트 중립성은 구호가 아니라 시험 가능한 주장으로 남습니다.
9
-
10
- ## 여기 담긴 것
11
-
12
- - **페이로드 번역.** 날것의 PreToolUse 페이로드가 `CovenantInput`(도구 호출과 서브에이전트 스폰)으로 바뀝니다. 서브에이전트 유형을 실은 `Task`
13
- 호출은 스폰으로 대응되고, 분류할 수 없는 페이로드는 번역 실패입니다. 실패는 추측으로 대체되는 대신 차단됩니다(fail-closed).
14
- - **가상 사후 상태(virtual post-state).** `Edit`·`Write`·`MultiEdit`가 적용되면 파일이 어떤 내용이 될지를 디스크를 건드리지 않고
15
- 계산합니다. 내용을 보는 약속은 지금의 파일이 아니라 제안된 결과를 판정합니다. 여러 편집의 순차 적용과 파일 생성 관례까지 계산에 들어갑니다.
16
- - **파일 변경 증거.** 디스크의 편집 전 상태와 가상 사후 상태를 짝지어 판별 유니온(discriminated union) 증거(편집 전 상태가 없으면 `create`,
17
- 있으면 `modify`)로 만들고, 변이 도구 호출 자신의 `fileChange` 필드에 싣습니다. 규율(discipline) 판정이 소비하는 증거가 이것입니다. 사후 상태가
18
- 성립하지 않으면 아무것도 내지 않고(같은 편집은 실제 도구도 거부합니다), 비변이 호출에 증거를 날조하지 않습니다.
19
- - **대화 기록 공급자.** `transcriptFromJsonlFile`이 세션 JSONL 파일을 `CanonicalTranscript`로 바꿉니다. 시간제 증인(TTL
20
- witness)의 실제 데이터 원천이며, 사람이 직접 친 것으로 확인된 메시지만 받아들이므로 AI가 자기 증언을 합성할 길이 없습니다. `findToolCalls`에도 답해
21
- `tool_use` 블록에서 도구 호출을 뽑아냅니다. 호출의 `input`이 평면 객체가 아니면 블록은 남기고 `args`만 비우는데, 호출이 있었다는 사실 자체가 증거이기
22
- 때문입니다. 읽기에 실패하면 빈 대화 기록이 아니라 `undefined`로 답합니다. 빈 세션은 아직 아무 말도 하지 않은 세션이라 판정 대상이고, 읽히지 않는 세션은 증거
23
- 통로 자체가 없어서 건너뜁니다. 어느 쪽이든 밸브는 닫히지, 열리지 않습니다.
24
- - **세션 공급 리더.** `sessionSourceReader({ repoRoot })`는 이 표면의 파일 리더입니다(작업 트리 위의 `SourceReader` —
25
- 항목 없음 · 디렉터리 · NUL 바이트 같은 부재는 `undefined`로 답하고, 권한 거부는 던집니다).
26
- `sessionChannelReader({ transcriptPath })`는 표면의 스폰 사이드카 채널입니다. 이 호스트가 대화 기록 옆
27
- `<dir>/<세션ID>/subagents/agent-*.meta.json`에 남기는 서브에이전트 기록을 파일명 정렬 순서의 JSON 배열 하나로 답합니다.
28
- `'[]'`는 스폰을 관측하지 못한 채널이고 `undefined`는 채널 자체가 없는 것 — 서로 다른 두 사실이며, 선언의 `supply` 정책이
29
- 처분하는 것은 둘째뿐입니다.
30
- 이 표면이 파싱하는 대화 기록(transcript)은 선언의 소스이기도 합니다(`{ transcript: true }`). 약속(covenant) 패키지가
31
- 공급 시점에 스냅샷으로 펴므로 어댑터는 그것을 위한 리더를 더하지 않습니다.
32
- - **텔레메트리 배선.** `runAdapterPath`가 깔때기 전체를 끝까지 실행합니다. 날 페이로드에서 번역(실패는 차단 1행을 기록하고 `2`로 종료), 주입된 이음새를
33
- 통한 판정, 깔때기 완결까지 이어져 호출마다 정확히 1행이 남습니다. 증언(witnessed)도 예외가 아닙니다. 판정 이음새를 주입으로 받는 이유는 이 패키지가
34
- covenant 패키지를 직접 가져오지(import) 않기 때문입니다. 의존은 코어를 통해서만, 단방향으로 흐릅니다.
35
-
36
- 아키텍처 청사진과 설계 근거는 [프로젝트 저장소](https://github.com/huskyhoochu/polydeukes)에 있습니다.
37
-
38
- ## 라이선스
39
-
40
- MIT
1
+ # `@polydeukes/adapter-claude-code`
2
+
3
+ [English](./README.md) · **한국어**
4
+
5
+ 어댑터는 Claude Code PreToolUse 페이로드를 약속(covenant) 입력 IR로 변환합니다.
6
+ 우산 패키지가 세션 표면에 주입할 읽기 함수를 만드는 팩터리도 제공합니다.
7
+
8
+ <a id="overview"></a>
9
+ ## 개요
10
+
11
+ 공개 계약 심볼은 다음과 같습니다.
12
+
13
+ - `runAdapterPath`
14
+ - `sessionSourceReader`
15
+ - `sessionChannelReader`
16
+ - `transcriptPathFromPayload`
17
+ - `transcriptFromJsonlFile`
18
+ - `COMMAND_ARGS`
19
+ - `MUTATING_TOOLS`
20
+ - `SHELL_TOOLS`
21
+
22
+ <a id="examples"></a>
23
+ ## 예제
24
+
25
+ ```ts
26
+ import { runAdapterPath } from '@polydeukes/adapter-claude-code';
27
+
28
+ const outcome = await runAdapterPath({
29
+ rawPayload: '{}',
30
+ telemetryPath: '.polydeukes/roi.log',
31
+ dispatch: async () => ({ exitCode: 0, results: [] }),
32
+ });
33
+ ```
34
+
35
+ <a id="see-also"></a>
36
+ ## 같이 보기
37
+
38
+ - [`@polydeukes/adapter-claude-code` 패키지
39
+ 레퍼런스](../../docs/reference/packages/adapter-claude-code.ko.md)
40
+ - [`polydeukes/claude-code`](../../docs/reference/packages/polydeukes.ko.md#polydeukes-entry-points)
41
+ - [`@polydeukes/covenant`](../../docs/reference/packages/covenant.ko.md)
package/README.md CHANGED
@@ -1,55 +1,41 @@
1
- # @polydeukes/adapter-claude-code
2
-
3
- **English** ·
4
- [한국어](https://github.com/huskyhoochu/polydeukes/blob/main/packages/adapter-claude-code/README.ko.md)
5
-
6
- > The boundary where Claude Code's vocabulary is translated away. PreToolUse hook payloads become
7
- the agent-neutral covenant input IR before anything reaches the core.
8
-
9
- **Alpha.** Agent and tool literals live *here* by design — this package exists so they never reach
10
- the core, which is how the core's agent-neutrality stays a testable claim rather than a slogan.
11
-
12
- ## What lives here
13
-
14
- - **Payload up-translation** — a raw PreToolUse payload becomes a `CovenantInput` (tool calls and
15
- subagent spawns). A `Task` call carrying a subagent type maps to a spawn; a payload that cannot be
16
- classified is a translation *failure*, and failures block (fail-closed) instead of degrading into
17
- a guess.
18
- - **Virtual post-state** — computes what a file *would* contain after an `Edit`/`Write`/`MultiEdit`
19
- applies, without touching disk. Content-aware covenants judge the proposed result, not the file as
20
- it currently is — including sequential multi-edit application and file-creation conventions.
21
- - **File-change evidence** — the disk pre-state pairs with the virtual post-state into union
22
- evidence (`create` when no pre-state exists, `modify` otherwise) attached to the mutating tool
23
- call's own `fileChange` field — the evidence discipline judgments consume. An unresolvable
24
- post-state yields nothing (the real tool rejects the same edit), and evidence is never fabricated
25
- for non-mutating calls.
26
- - **Transcript provider** `transcriptFromJsonlFile` turns a session JSONL file into a
27
- `CanonicalTranscript`, the TTL witness's real data source: only positively-identified human-typed
28
- messages are admitted, so an AI can never synthesize its own witness. It answers `findToolCalls`
29
- too, extracting calls from `tool_use` blocks — when a call's `input` is not a flat object the
30
- block still yields a call with empty `args`, because the existence of the call is itself the
31
- evidence. A read failure answers `undefined` rather than an empty transcript — an empty session
32
- has said nothing yet and is judged, an unreadable one is no evidence channel at all and is
33
- skipped. Either way the valve turns off, never open.
34
- - **Session supply readers** — `sessionSourceReader({ repoRoot })` is this surface's file
35
- reader (a `SourceReader` over the working tree: absence — no entry, a directory, NUL bytes —
36
- answers `undefined`, a permission refusal throws), and `sessionChannelReader({ transcriptPath })`
37
- is its spawn-sidecar channel: the subagent records this host keeps at
38
- `<dir>/<sessionId>/subagents/agent-*.meta.json` beside the transcript, answered as one JSON
39
- array in filename order. `'[]'` is a channel that observed no spawn; `undefined` is no
40
- channel at all — two different facts, and the declaration's `supply` policy disposes only of
41
- the second. The transcript this surface parses is also a declaration source (`{ transcript:
42
- true }`): the covenant flattens it into a snapshot at supply time, so this adapter adds no
43
- reader for it.
44
- - **Telemetry wiring** — `runAdapterPath` drives the full funnel: raw payload → translation (a
45
- failure logs one blocked record and exits `2`) → dispatch through an *injected* seam → funnel
46
- completion, so exactly one record lands per call, witnessed rows included. The dispatch seam is
47
- injected because this package never imports the covenant package — dependencies stay one-way,
48
- through the core only.
49
-
50
- See the [project repository](https://github.com/huskyhoochu/polydeukes) for the architecture
51
- blueprint and design rationale.
52
-
53
- ## License
54
-
55
- MIT
1
+ # `@polydeukes/adapter-claude-code`
2
+
3
+ **English** · [한국어](./README.ko.md)
4
+
5
+ This adapter translates Claude Code PreToolUse payloads into covenant input IR and provides the
6
+ session-side reader factories the umbrella injects.
7
+
8
+ <a id="overview"></a>
9
+ ## Overview
10
+
11
+ Public contract symbols include:
12
+
13
+ - `runAdapterPath`
14
+ - `sessionSourceReader`
15
+ - `sessionChannelReader`
16
+ - `transcriptPathFromPayload`
17
+ - `transcriptFromJsonlFile`
18
+ - `COMMAND_ARGS`
19
+ - `MUTATING_TOOLS`
20
+ - `SHELL_TOOLS`
21
+
22
+ <a id="examples"></a>
23
+ ## Examples
24
+
25
+ ```ts
26
+ import { runAdapterPath } from '@polydeukes/adapter-claude-code';
27
+
28
+ const outcome = await runAdapterPath({
29
+ rawPayload: '{}',
30
+ telemetryPath: '.polydeukes/roi.log',
31
+ dispatch: async () => ({ exitCode: 0, results: [] }),
32
+ });
33
+ ```
34
+
35
+ <a id="see-also"></a>
36
+ ## See also
37
+
38
+ - [`@polydeukes/adapter-claude-code` package
39
+ reference](../../docs/reference/packages/adapter-claude-code.md)
40
+ - [`polydeukes/claude-code`](../../docs/reference/packages/polydeukes.md#polydeukes-entry-points)
41
+ - [`@polydeukes/covenant`](../../docs/reference/packages/covenant.md)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@polydeukes/adapter-claude-code",
3
- "version": "0.6.0",
3
+ "version": "0.6.1",
4
4
  "description": "Polydeukes adapter for Claude Code — up-translates PreToolUse hook payloads into the agent-neutral covenant input IR. Alpha.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -32,10 +32,10 @@
32
32
  "@types/node": "^24.0.0",
33
33
  "typescript": "7.0.2",
34
34
  "vitest": "^4.1.0",
35
- "@polydeukes/core": "^0.6.0"
35
+ "@polydeukes/core": "^0.6.1"
36
36
  },
37
37
  "peerDependencies": {
38
- "@polydeukes/core": "^0.6.0"
38
+ "@polydeukes/core": "^0.6.1"
39
39
  },
40
40
  "scripts": {
41
41
  "build": "tsc -p tsconfig.build.json",