@odyssey365/cli 0.2.3 → 0.2.5

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.
@@ -5,7 +5,7 @@
5
5
  // 입구는 둘 — 감시 태그를 단 할일, 그리고 아무 항목의 댓글에 내가 쓴 멘션(@클로드코드).
6
6
  // 디스패처는 우체부다. 판단·작업·답글·상태 변경은 깨운 세션의 Claude 가 Odyssey MCP 로 한다.
7
7
  // 디스패처가 직접 쓰는 건 멘션의 받았다 표시와 일꾼이 남기지 못한 실패 알림뿐이다. 모델은 부르지 않는다(일이 없으면 토큰 0).
8
- // 명세: odyssey agent-guide --watch-agent (저장소 back_end/odyssey_cli/prompts/watch-agent.md)
8
+ // 명세: 같은 폴더의 SPEC.md (저장소 back_end/odyssey_cli/examples/watch-dispatcher/SPEC.md) — 권하는 길은 세션 듣기(examples/watch-agent)
9
9
  //
10
10
  // 실행: node dispatcher.mjs (실제 모드)
11
11
  // node dispatcher.mjs --dry-run (일꾼을 부르지 않고 "누구를 어떤 메시지로 깨울지"만 로그)
@@ -119,7 +119,7 @@ export const PHASES = ['running', 'idle', 'done', 'blocked', 'cancelled'];
119
119
  const DELIVERED_KEEP = 1000; // 항목당 기억하는 배달 댓글 수(파일이 끝없이 커지지 않게)
120
120
  const AGENT_KEEP = 300; // 항목당 기억하는 에이전트 댓글 uid 수 — 옛 감시(--include-agent)용. 이제 답글 대상은 감시가 replyTo 로 알려 준다
121
121
 
122
- /** 일꾼이 답글을 달 수 있는 항목 종류 — comment_on_item 의 itemType + 보드 전체(comment_on_project). */
122
+ /** 일꾼이 답글을 달 수 있는 항목 종류 — comment_on_item 의 itemType(보드 전체 project 포함 — 옛 comment_on_project). */
123
123
  export const COMMENT_ITEM_TYPES = Object.freeze([
124
124
  'todo', 'memo', 'asset', 'event', 'routine', 'routineInstance', 'locationMap', 'record', 'companionReport', 'projectComponent', 'project',
125
125
  ]);
@@ -320,9 +320,10 @@ function tagWorkerRules(cfg, { title, todoUid, ref, myUid }) {
320
320
  ].join('\n');
321
321
  }
322
322
 
323
+ // 루틴 · 기록 · 에셋 상세는 fetch("타입:uid") — get_routine · get_record · get_asset 은 MCP 목록에서 숨었다(부르면 돌지만 일꾼의 도구 목록엔 없다).
323
324
  const READ_TOOL = {
324
- todo: 'get_todo', memo: 'get_memo', event: 'get_event', record: 'get_record', routine: 'get_routine',
325
- asset: 'get_asset', companionReport: 'get_report', project: 'get_project', projectComponent: 'get_project_components',
325
+ todo: 'get_todo', memo: 'get_memo', event: 'get_event', record: 'fetch("record:<uid>")', routine: 'fetch("routine:<uid>")',
326
+ asset: 'fetch("asset:<uid>")', companionReport: 'get_report', project: 'get_project', projectComponent: 'get_project_components',
326
327
  };
327
328
 
328
329
  /** list_item_comments·comment_on_item 에 넘길 대상 인자(사람이 읽는 글로). */
@@ -338,7 +339,8 @@ function mentionWorkerRules(cfg, { ref }) {
338
339
  const read = READ_TOOL[r.itemType];
339
340
  const board = r.itemType === 'project';
340
341
  const who = `authorName "${cfg.authorName}", authorEmoji "${cfg.authorEmoji}", notify false`;
341
- const reply = board ? `comment_on_project(projectId "${r.itemUid}", ${who})` : `comment_on_item(${threadArgsText(r)}, ${who})`;
342
+ // 보드 전체도 comment_on_item(itemType "project") — 옛 comment_on_project 는 MCP 목록에서 빠졌다(서버가 옛 이름도 받는다).
343
+ const reply = board ? `comment_on_item(itemType "project", itemUid "${r.itemUid}", ${who})` : `comment_on_item(${threadArgsText(r)}, ${who})`;
342
344
  const ask = board ? 'notify false 그대로 — 보드 전체 댓글엔 나만 알림이 없다' : 'notifyMe true — 나한테만 알림';
343
345
  const mention = cfg.mentions[0];
344
346
  return [
@@ -398,10 +400,14 @@ export function ackContent(cfg, busy) {
398
400
  return busy ? `${base.replace(/[.。\s]+$/u, '')} — 앞의 일을 마치면 이어서 볼게요.` : base;
399
401
  }
400
402
 
401
- /** 6절 답글 자리 — 보드 전체는 comment_on_project(나만 알림 없음), 카드는 보드(projectId)까지, 그 밖은 comment_on_item. */
403
+ /**
404
+ * 6절 답글 자리 — 보드 전체는 comment_on_item(itemType "project" · 나만 알림 없음), 카드는 보드(projectId)까지, 그 밖도 comment_on_item.
405
+ * 디스패처가 CLI 로 직접 다는 댓글(받았다 표시 · 실패 알림)도 지금 이름을 쓴다 — CLI 는 목록에 없는 옛 이름(comment_on_project)을
406
+ * 서버에 보내기 전에 막는다(261110 MCP 100개 판 배포 뒤).
407
+ */
402
408
  export function replyTarget(ref) {
403
409
  const r = asRef(ref);
404
- if (r.itemType === 'project') return { tool: 'comment_on_project', params: { projectId: r.itemUid }, canNotifyMe: false };
410
+ if (r.itemType === 'project') return { tool: 'comment_on_item', params: { itemType: 'project', itemUid: r.itemUid }, canNotifyMe: false };
405
411
  if (r.itemType === 'projectComponent') {
406
412
  return { tool: 'comment_on_item', params: { itemType: 'projectComponent', itemUid: r.itemUid, projectId: r.projectId }, canNotifyMe: true };
407
413
  }
@@ -578,7 +584,7 @@ export function createWorkerRunner(cfg, log) {
578
584
  };
579
585
  }
580
586
 
581
- /** 실제 댓글(받았다 표시·실패 알림) — odyssey comment_on_item / comment_on_project. */
587
+ /** 실제 댓글(받았다 표시·실패 알림) — odyssey comment_on_item(보드 전체는 itemType project). */
582
588
  export function createCommentPoster(cfg, log) {
583
589
  return async ({ ref, todoUid, content, notifyMe = true }) => {
584
590
  const args = buildCommentArgs(cfg, ref ?? todoUid, content, { notifyMe });
@@ -0,0 +1,6 @@
1
+ config.json
2
+ state*.json
3
+ *.lock
4
+ *.tmp
5
+ logs/
6
+ test/.tmp/
@@ -0,0 +1,12 @@
1
+ {
2
+ "name": "odyssey-watch-agent-example",
3
+ "private": true,
4
+ "type": "module",
5
+ "engines": { "node": ">=20" },
6
+ "scripts": {
7
+ "check": "node dispatcher.mjs --check",
8
+ "dry-run": "node dispatcher.mjs --dry-run",
9
+ "start": "node dispatcher.mjs",
10
+ "test": "node --test test/*.test.mjs"
11
+ }
12
+ }
@@ -680,14 +680,16 @@ test('보드 카드 멘션 — 키와 답글 자리에 보드(projectId)까지
680
680
  assert.deepEqual(h.comments[0].ref, { itemType: 'projectComponent', itemUid: 'K1', projectId: 'B1' });
681
681
  });
682
682
 
683
- test('보드 전체 멘션 — comment_on_project · 나만 알림이 없어 notify false 로만', async () => {
683
+ test('보드 전체 멘션 — comment_on_item(itemType project) · 나만 알림이 없어 notify false 로만', async () => {
684
684
  const h = harness();
685
685
  await h.send(ready(), comment('C1', 'B1', { itemType: 'project', text: MENTION_TEXT }));
686
- assert.match(h.calls[0].systemPrompt, /comment_on_project\(projectId "B1", authorName "Claude", authorEmoji "✨", notify false\)/);
686
+ // 일꾼(MCP)에겐 지금 이름 — 옛 comment_on_project 는 MCP 목록에 없다. 디스패처 자신의 CLI 호출(받았다 표시)도 지금 이름(CLI 가 옛 이름을 막는다).
687
+ assert.match(h.calls[0].systemPrompt, /comment_on_item\(itemType "project", itemUid "B1", authorName "Claude", authorEmoji "✨", notify false\)/);
688
+ assert.doesNotMatch(h.calls[0].systemPrompt, /comment_on_project/);
687
689
  assert.match(h.calls[0].systemPrompt, /보드 전체 댓글엔 나만 알림이 없다/);
688
690
  const ack = buildCommentArgs(DEFAULT_CONFIG, { itemType: 'project', itemUid: 'B1' }, '👀 받았어요.', { notifyMe: true });
689
- assert.deepEqual(ack.slice(0, 4), ['-p', 'default', 'comment_on_project', '--json']);
690
- assert.deepEqual(JSON.parse(ack[4]), { projectId: 'B1', content: '👀 받았어요.', authorName: 'Claude', authorEmoji: '✨', notify: false });
691
+ assert.deepEqual(ack.slice(0, 4), ['-p', 'default', 'comment_on_item', '--json']);
692
+ assert.deepEqual(JSON.parse(ack[4]), { itemType: 'project', itemUid: 'B1', content: '👀 받았어요.', authorName: 'Claude', authorEmoji: '✨', notify: false });
691
693
  });
692
694
 
693
695
  test('받지 않는 종류(스냅샷 등)의 멘션 · 멘션 없는 남의 항목 댓글 → 무시', async () => {
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@odyssey365/cli",
3
- "version": "0.2.3",
3
+ "version": "0.2.5",
4
4
  "description": "Odyssey365 / Odyssey60 / Odyssey30 CLI — 터미널·AI 에이전트에서 할일·메모·루틴·기록·보드·페이지를 다룬다 (OdysseyCLI)",
5
5
  "type": "module",
6
6
  "engines": {
@@ -21,7 +21,7 @@
21
21
  "build": "tsc",
22
22
  "prepack": "npm run build",
23
23
  "prepublishOnly": "npm test && npm run test:package",
24
- "test": "npm run build && node --test test/*.test.mjs examples/watch-agent/test/*.test.mjs",
24
+ "test": "npm run build && node --test test/*.test.mjs examples/watch-agent/test/*.test.mjs examples/watch-dispatcher/test/*.test.mjs",
25
25
  "test:package": "node scripts/package-smoke.mjs",
26
26
  "dev": "node dist/index.js"
27
27
  },
@@ -1,8 +1,8 @@
1
1
  # Odyssey 위에 에이전트 설계하기 — 사례집
2
2
 
3
3
  > **쓰는 법** — Odyssey 를 입구로 두고 PC 에서 일하는 에이전트·프로그램을 **만들기 전에** 읽는다(`odyssey agent-guide --design`).
4
- > 이 문서는 코드가 아니라 **결정과 그 이유**다. 실제로 도는 정답은 `odyssey watch-agent init <새폴더>` 예제,
5
- > 그 예제를 처음부터 짜게 하는 명세는 `odyssey agent-guide --watch-agent` 다.
4
+ > 이 문서는 코드가 아니라 **결정과 그 이유**다. 실제로 도는 정답은 `odyssey watch-agent init <새폴더>` 예제(세션 듣기),
5
+ > 그 세션이 따르는 규칙과 듣기의 계약은 `odyssey agent-guide --watch-agent` 다.
6
6
  >
7
7
  > 순서: ① 아래 일곱 질문에 답한다 → ② 5절 견본대로 **설계 제안서**를 써서 사람에게 먼저 보인다 → ③ 승인되면 만든다.
8
8
  > 도구 이름·파라미터는 서버가 정본이다 — 쓰기 전에 `odyssey describe <도구>` 로 확인한다.
@@ -14,12 +14,12 @@
14
14
  | 질문 | 감시 에이전트의 답 | 답을 안 정하면 |
15
15
  |---|---|---|
16
16
  | **입구** — 사람이 앱에서 무엇을 하면 일이 시작되나 | 할일에 태그(`클로드 코드`) · 아무 항목 댓글에 멘션(`@클로드코드`) | 사람이 "어떻게 맡기지?"를 모른다. 버튼을 새로 만들 일이 아니다 — 태그·댓글이 이미 있는 입구다 |
17
- | **감지** — 일이 생긴 걸 어떻게 아나 | `odyssey watch` 실시간 NDJSON | 매분 `list_*` 폴링 → 지연·쿼터. 반대로 실시간이 필요 없는 일에 감시를 띄우면 상시 프로세스를 떠안는다 |
17
+ | **감지** — 일이 생긴 걸 어떻게 아나 | 일하는 세션이 띄운 듣기(`odyssey watch` 실시간 NDJSON을 거른다) | 매분 `list_*` 폴링 → 지연·쿼터. 반대로 실시간이 필요 없는 일에 감시를 띄우면 상시 프로세스를 떠안는다 |
18
18
  | **대화창** — 결과·질문을 어디에 쓰고 사람 답을 어디서 받나 | 그 항목의 댓글 스레드 | 결과가 새 메모·새 할일로 흩어져 사람이 못 찾는다 |
19
- | **판단** — 프로그램이 정할 것과 모델이 정할 것 | 프로그램 = 배달 표(규칙) · 모델 = 할 일인가·물을까·끝났나 | 프로그램에 판단을 넣으면 굳고, 모델에 배달을 맡기면 대기 중에도 돈이 든다 |
20
- | **지시의 주인** — 누구 글을 지시로 읽나 | 내 계정의 글(`author:"me"`)만. 에이전트·남의 글은 자료 | 공유 보드 멤버의 댓글이 내 저장소의 일꾼을 움직인다(프롬프트 주입 통로) |
21
- | **멱등** — 재시작·중복 이벤트에서 두 번 하지 않으려면 무엇을 적나 | `state.json` — 항목별 세션 id · 배달한 댓글 uid · 커서 | 재시작마다 같은 일을 다시 하거나, 놓친 댓글을 영영 잃는다 |
22
- | **멈춤** — 돈·권한·실패를 어디서 막고 어떻게 알리나 | 한 턴·하루 예산 · 금지 도구 차단 · 실패 시 스레드에 한 줄 | 조용히 돈이 새거나, 일꾼이 죽은 줄 모르고 사람이 기다린다 |
19
+ | **판단** — 프로그램이 정할 것과 모델이 정할 것 | 프로그램 = 깨울 표(규칙) · 모델 = 할 일인가·물을까·끝났나 | 프로그램에 판단을 넣으면 굳고, 모델에 거르기를 맡기면 대기 중에도 돈이 든다 |
20
+ | **지시의 주인** — 누구 글을 지시로 읽나 | 내 계정의 글(`author:"me"`)만. 에이전트·남의 글은 자료 | 공유 보드 멤버의 댓글이 내 저장소의 세션을 움직인다(프롬프트 주입 통로) |
21
+ | **멱등** — 재시작·중복 이벤트에서 두 번 하지 않으려면 무엇을 적나 | 듣기 상태 — 커서(since) · 낸 댓글 uid · 본 태그 할일 · 맡은 스레드 | 다시 띄울 때마다 같은 일을 다시 하거나, 놓친 댓글을 영영 잃는다 |
22
+ | **멈춤** — 돈·권한·실패를 어디서 막고 어떻게 알리나 | 그 세션의 권한 설정(금지 도구 차단) · 깨울 때만 토큰 · 듣기 오류는 세션이 한 번 다시, 또 실패면 사람에게 | 조용히 돈이 새거나, 귀가 먹은 줄 모르고 사람이 기다린다 |
23
23
 
24
24
  여기에 하나 더 — **끝**: 일이 끝나면 무엇으로 닫고(할일 완료·답글), 언제 귀를 뗄까(관심 스레드, 2절).
25
25
 
@@ -28,32 +28,34 @@
28
28
  ## 1. 해부 — 감시 에이전트는 왜 이렇게 생겼나
29
29
 
30
30
  ```
31
- 사람(앱) ── 태그·댓글 ──▶ Odyssey 서버 ── odyssey watch(NDJSON) ──▶ 디스패처 ── 세션 id 로 깨움 ──▶ 일꾼 세션
32
- ▲ (모델 없음) (Claude Code + Odyssey MCP)
31
+ 사람(앱) ── 태그·댓글 ──▶ Odyssey 서버 ── odyssey watch(NDJSON) ──▶ 듣기 ── 끝나며(또는 줄마다) 깨움 ──▶ 일하는 세션
32
+ ▲ (모델 없음) (Claude Code + Odyssey MCP)
33
33
  └──────────────────────────── 답글·상태 (comment_on_item · update_todo · complete_todo) ◀──────────────┘
34
34
  ```
35
35
 
36
36
  | 결정 | 이유 | 빼면 생기는 일 |
37
37
  |---|---|---|
38
- | **디스패처는 배달만, 답글·판단은 일꾼** | 쓰는 곳이 하나여야 답이 안 겹친다. 판단은 모델이 스레드를 읽고 한다 | 디스패처와 일꾼이 둘 다 답글 → 중복. 디스패처에 if 문이 쌓여 굳는다 |
39
- | **대기 중엔 모델을 부르지 않는다** | 감시·배달은 결정적 코드로 충분하다 | 일이 없어도 토큰이 든다 |
40
- | **항목 하나 = 세션 하나** | 맥락이 작고, 며칠 뒤 답해도 앞 대화를 기억한 채 이어 간다(`--resume`) | 세션 하나에 모든 일을 넣으면 맥락이 섞이고 비싸진다 |
41
- | **질문하고 기다리는 건 디스패처 몫** | 일꾼은 질문 답글을 남기고 턴을 끝낸다. 답이 오면 디스패처가 같은 세션을 깨운다 | 일꾼이 기다리며 돌면 타임아웃·돈 |
42
- | **세션 id 는 디스패처가 먼저 정해 적는다** | 일꾼이 도중에 죽어도 같은 세션으로 이어 받는다 | 죽은 실행의 맥락을 잃고 처음부터 다시 |
43
- | **"배달했다" = 일꾼을 띄우기 직전** | 큐에 넣을 때 적으면 재시작 때 큐 안의 일을 잃는다 | 꺼졌다 켜면 맡긴 일이 사라진다 |
44
- | **커서 = 아직 배달 안 한 가장 이른 댓글의 바로 앞** | 경계에서 다시 온 댓글은 `delivered` 로 거른다 | 마지막 배달 시각만 쓰면 큐 뒤의 더 이른 댓글을 잃는다 |
45
- | **`todo modified` 로는 깨우지 않는다** | 일꾼이 바꾼 상태가 다시 들어오는 메아리다 | 일꾼 → 상태 변경 → 다시 깨움 → 무한 반복 |
38
+ | **일하는 세션이 직접 듣는다**(별도 디스패처·헤드리스 일꾼을 두지 않는다) | 그 세션이 앱 세션 목록에 보여 사람이 들여다보고 끼어든다 · 권한은 그 세션 설정 그대로 · 처리한 맥락을 이어 간다 | 항목마다 안 보이는 일꾼이 따로 돌고, 일꾼마다 권한·예산·자동 시작을 다시 짜야 한다 |
39
+ | **듣기는 깨우기만, 판단·답글은 세션** | 쓰는 곳이 하나여야 답이 안 겹친다. 판단은 모델이 스레드를 읽고 한다 | 듣기 스크립트에 if 문이 쌓여 굳는다 · 둘이 답글을 달면 중복 |
40
+ | **기다리는 동안엔 모델을 부르지 않는다** | 감시·거르기는 결정적 코드로 충분하다. 세션은 깨울 때만 토큰을 쓴다 | 일이 없어도 토큰이 든다 |
41
+ | **오래 들을 땐 백그라운드 종료, 잠깐은 Monitor** | 이벤트에 끝나는 듣기는 만료가 없고 일이 있을 때만 깨운다. 줄마다 알리는 장치는 편하지만 만료(30분)마다 다시 걸어야 한다 | 30분마다 다시 걸며 CLI 세션 발급(하루 200)을 쓰고 빈 알림에 깬다 |
42
+ | **질문하고 기다리는 건 듣기 몫** | 세션은 질문 답글을 남기고 턴을 끝낸다. 사람 답이 그 스레드에 오면 듣기가 세션을 다시 깨운다 | 세션이 답을 기다리며 돌면 시간·돈 |
43
+ | **"냈다" = 출력하기 직전에 상태에 적는다** | 다시 띄워도 두 번 내지 않는다 | 다시 띄울 때마다 같은 일을 또 한다 |
44
+ | **커서는 ready 에서만 "띄운 시각 − 1분"으로 당긴다** | 밀린 댓글은 흐름 여럿이 섞여 시간순이 아니다. 경계에서 다시 온 것은 `seen` 으로 거른다 | 낸 댓글 시각으로 당기면 더 이른 댓글을 잃는다 |
45
+ | **`todo modified` 로는 깨우지 않는다** | 세션이 바꾼 상태가 다시 들어오는 메아리다 | 세션 → 상태 변경 → 다시 깨움 → 무한 반복 |
46
46
  | **에이전트 댓글(`authorKind`)엔 반응하지 않는다** | 감시는 기본으로 에이전트 댓글을 빼고 낸다 | 자기 답글에 다시 답하는 메아리 |
47
- | **남의 댓글(`author:"other"`)은 배달하지 않는다** | 지시는 내 글뿐. 일꾼은 다음에 깨어날 때 스레드를 읽어 맥락으로만 본다 | 공유 보드 멤버가 내 저장소에서 명령을 실행시킨다 |
48
- | **금지는 도구 차단으로**(`--disallowedTools`) | 프롬프트 문장은 어겨질 수 있다. 헤드리스는 허락 안 한 도구를 거절한다 | `git push`·배포가 "하지 마"라는 문장 하나에 걸린다 |
49
- | **한 턴·하루 예산** | 헤드리스는 한 단어 답에도 고정비(약 $0.2)가 든다 | 밤새 돈이 샌다 |
50
- | **작업 폴더당 동시 하나(FIFO)** | 같은 저장소를 두 세션이 고치면 충돌한다 | 반쯤 섞인 변경 |
51
- | **단일 실행 잠금** | 디스패처가 둘이면 같은 댓글이 두 번 배달된다 | 같은 일 두 번, 돈 두 배 |
52
- | **`--check` → `--dry-run` → 실제** | 배달 표를 돈 쓰기 전에 사람이 본다 | 첫 실행에서 밀린 태그 할일이 한꺼번에 돈다 |
53
- | **리스너 `error` 뒤엔 감시를 다시 띄운다**(백오프 5초→5분 · `ready` 120초 제한) | Firestore 리스너는 오류를 내면 그 자리에서 끝난다 | 조용히 귀가 먹은 채 "켜져 있음" |
47
+ | **남의 댓글(`author:"other"`)로는 깨우지 않는다** | 지시는 내 글뿐. 세션은 다음에 깨어날 때 스레드를 읽어 맥락으로만 본다 | 공유 보드 멤버가 내 저장소에서 명령을 실행시킨다 |
48
+ | **금지는 도구 차단으로**(세션의 권한 설정 · Claude Code 면 `permissions.deny`) | 프롬프트 문장은 어겨질 수 있다. 깨어난 턴엔 승인할 사람이 없다 | `git push`·배포가 "하지 마"라는 문장 하나에 걸린다 |
49
+ | **듣기는 하나**(잠금) | 듣기가 둘이면 같은 이벤트로 세션 둘이 깨어나 같은 일을 한다 | 같은 일 두 번, 돈 두 배 |
50
+ | **일 하나 마감 뒤 맥락을 비운다 — 듣기를 먼저 끄고** | 깨울 때마다 맥락이 쌓인다. 상태가 파일에 있어 비운 뒤 이어 듣는다 | 맥락이 커져 비싸지고, 끄지 않고 비우면 맥락 없는 세션이 깬다 |
51
+ | **`--check` → `--dry-run` → 실제** | 밀린 태그 할일이 처음 켤 때 한꺼번에 온다 — 먼저 사람이 본다 | 오래전 태그 할일까지 한꺼번에 돈다 |
52
+ | **리스너 `error` 뒤엔 끝내고 다시 띄운다**(`ready` 120초 제한) | Firestore 리스너는 오류를 내면 그 자리에서 끝난다 | 조용히 귀가 먹은 채 "듣는 중" |
54
53
  | **매시간 stderr 의 `UNAUTHENTICATED`(Code 16)는 정상** | 서버가 1시간 된 스트림을 끊고 SDK 가 새 토큰으로 다시 붙는 토큰 교대다 | 정상 신호를 장애로 세어 재시작을 남발한다 |
55
54
 
56
- 자세한 배달 표·상태 파일·일꾼 규칙 원문: `odyssey agent-guide --watch-agent` 2~8절.
55
+ 대가도 결정이다 — **세션이 살아 있을 때만 듣는다**. 세션을 띄워 둘 수 없어 사람 없이 상시로 돌려야 하면 무인 대안
56
+ `odyssey watch-agent init <새 폴더> --dispatcher`(항목마다 헤드리스 일꾼 · 일꾼 권한·예산을 도구 차단으로 따로 건다 · 명세는 그 폴더의 `SPEC.md`).
57
+
58
+ 자세한 깨울 표·세션 규칙·듣기의 계약: `odyssey agent-guide --watch-agent` 2~6절.
57
59
 
58
60
  ---
59
61
 
@@ -64,7 +66,7 @@
64
66
  | 갈래 | 오는 댓글 | 어떻게 붙나 | 언제 빠지나 |
65
67
  |---|---|---|---|
66
68
  | **내 댓글** | 모든 스레드의 내 계정 댓글 | 늘 온다(등록 불필요) | 빠지지 않는다(`--no-comments` 로만 끔) |
67
- | **관심 스레드** (`followed:true`) | 그 방의 **남의** 댓글까지(공유 보드 멤버 · 앱 「답글」) | 자동 — 에이전트가 `comment_on_item`·`comment_on_project` 로 댓글을 남기면(`source:"auto"`) · 수동 — `odyssey threads follow`(`source:"manual"`) | 마지막 **에이전트 활동**(댓글·follow) 뒤 `ttlDays`(기본 14일, 1~365) 조용하면. 사람 댓글로는 늘지 않는다 · `odyssey threads unfollow` |
69
+ | **관심 스레드** (`followed:true`) | 그 방의 **남의** 댓글까지(공유 보드 멤버 · 앱 「답글」) | 자동 — 에이전트가 `comment_on_item`(보드 전체는 `itemType "project"`) 로 댓글을 남기면(`source:"auto"`) · 수동 — `odyssey threads follow`(`source:"manual"`) | 마지막 **에이전트 활동**(댓글·follow) 뒤 `ttlDays`(기본 14일, 1~365) 조용하면. 사람 댓글로는 늘지 않는다 · `odyssey threads unfollow` |
68
70
  | **태그 항목 스레드** (`tagged:true`) | `--tag` 가 걸린 내 할일·메모·프로젝트(+그 보드의 카드)·리포트의 방 | 태그가 곧 등록 | 태그를 떼면 바로(`reason:"untagged"`) — 만료 없음 |
69
71
 
70
72
  감시에서 갈래째 끄기: `--no-comments`(내 댓글) · `--no-threads`(관심 스레드) · `--no-tag-threads`(태그 항목 스레드).
@@ -80,7 +82,7 @@ odyssey threads follow --itemType projectComponent --itemUid <카드 id> --proje
80
82
  odyssey threads unfollow --roomUid <방> # 또는 --itemType · --itemUid (· --projectId)
81
83
  ```
82
84
 
83
- 도구 이름 그대로 `follow_thread` · `unfollow_thread` · `list_followed_threads` 도 된다(MCP 커넥터에서도 같은 도구).
85
+ 도구 이름 그대로 `follow_thread`(`follow:false` = 빼기) · `list_followed_threads` 도 된다(MCP 커넥터에서도 같은 도구).
84
86
 
85
87
  **설계 규칙**
86
88
 
@@ -91,19 +93,19 @@ odyssey threads unfollow --roomUid <방> # 또는 --it
91
93
  4. **할일 완료로는 빠지지 않는다(일부러).** 완료 뒤에도 이어지는 말이 있을 수 있다. 조용하면 기간 뒤 저절로 빠진다.
92
94
  5. **`author:"other"` 는 지시가 아니다** — 요약·알림의 재료일 뿐, 실행하지 않는다.
93
95
  6. **한도**: 감시 하나가 귀를 대는 방은 관심 스레드 최근 활동 순 100개 · 태그 방 최근 댓글 순 200개. 넘치면 오래된 방이 빠진다(`reason:"limit"`).
94
- 7. **`thread` 이벤트**(`followed`/`unfollowed`, `reason` = manual·expired·forbidden·limit·untagged)는 배달 판단에 쓰지 말고 로그로만 남긴다.
96
+ 7. **`thread` 이벤트**(`followed`/`unfollowed`, `reason` = manual·expired·forbidden·limit·untagged)는 깨울 판단에 쓰지 말고 로그로만 남긴다.
95
97
 
96
98
  ---
97
99
 
98
100
  ## 3. 뼈대를 빌려 쓰는 법
99
101
 
100
- 감시 에이전트의 뼈대 = **입구(태그·멘션) → 감지(watch) → 배달(결정적 코드) → 일(모델 세션) → 대화창(스레드)**.
102
+ 감시 에이전트의 뼈대 = **입구(태그·멘션) → 감지(watch) → 깨우기(결정적 코드 — 듣기) → 일(일하는 세션) → 대화창(스레드)**.
101
103
  새 설계는 이 다섯 칸 중 무엇을 바꾸는지로 적는다. 바꾸지 않는 칸은 예제의 결정(1절)을 그대로 물려받는다.
102
104
 
103
105
  | 바꾸는 칸 | 예 | 같이 바꿔야 할 것 |
104
106
  |---|---|---|
105
- | 일꾼 | Claude Code → 다른 에이전트 CLI | 필요 조건: 세션 id 로 새로 만들기 · 이어 받기 · MCP 도구 · 비용 출력. 예제는 일꾼 깨우는 절만 바꾸면 된다 |
106
- | 일꾼 권한 | 읽기 전용(조사·리뷰) | 허락 목록에서 편집·셸을 빼고, 결과는 리포트(`create_report`)로 |
107
+ | 세션 | Claude Code → 다른 코딩 에이전트 | 필요 조건: 백그라운드 프로세스가 끝나면(또는 출력 줄마다) 세션을 깨우는 기능 · Odyssey 도구(MCP 또는 CLI). 듣기는 그대로 쓴다 |
108
+ | 세션 권한 | 읽기 전용(조사·리뷰) | 그 세션의 권한 설정에서 편집·셸을 막고, 결과는 리포트(`create_report`)로 |
107
109
  | 입구 | 태그 대신 특정 보드의 카드 | 항목 키(보드 카드는 `projectComponent:<보드>/<카드>`)와 답글 자리 |
108
110
  | 감지 | 실시간 → 하루 한 번 | 감시를 버리고 `launchd`/`cron` + `get_context`·`list_*` |
109
111
  | 대화창 | 스레드 → 알림 | `send_notification`(나에게만) — 알림이 폭주하지 않게 묶는다 |
@@ -115,16 +117,16 @@ odyssey threads unfollow --roomUid <방> # 또는 --it
115
117
  ### A. 읽기 전용 리뷰어 — 권한만 바꾼 감시 에이전트
116
118
 
117
119
  - **입구**: 할일 태그 `리뷰`. 본문에 PR 주소.
118
- - **바뀌는 것**: 일꾼 권한 — 파일 편집·셸 금지, `gh pr view`·`gh pr diff` 같은 읽기만 허락. 결과는 할일 스레드 답글 하나(길면 리포트 + 답글에 링크).
119
- - **물려받는 것**: 배달 표 · 세션 · 메아리 방지 · 예산 전부.
120
+ - **바뀌는 것**: 듣는 세션의 권한 — 파일 편집·셸 금지, `gh pr view`·`gh pr diff` 같은 읽기만 허락. 결과는 할일 스레드 답글 하나(길면 리포트 + 답글에 링크).
121
+ - **물려받는 것**: 깨울 표 · 듣기 상태 · 메아리 방지 전부(듣기 `config.json` 의 `watchTag` 만 `리뷰`로).
120
122
  - **조심**: PR 본문·코드 주석에 적힌 "이렇게 해라"는 지시가 아니라 자료다.
121
123
 
122
124
  ### B. 공유 보드 비서 — 남의 답을 받아 나에게 전한다
123
125
 
124
126
  - **입구**: 보드에서 내가 멤버에게 질문 댓글을 남기며 비서를 부른다(멘션). 비서가 같은 스레드에 "답이 오면 알려 드릴게요"를 단다 → 자동 관심 스레드.
125
127
  일주일 넘게 걸릴 질문이면 `odyssey threads follow … --days 30`.
126
- - **감지**: `odyssey watch` 의 `author:"other"`, `followed:true` 댓글.
127
- - **판단**: 디스패처가 그 방의 남 댓글을 모아(예: 10분) 일꾼 하나에 넘기고, 일꾼은 **요약만** 한다 — 남의 글을 실행하지 않는다.
128
+ - **감지**: `odyssey watch` 의 `author:"other"`, `followed:true` 댓글 — 듣기를 고쳐 관심 스레드를 켜고(`followedThreads:true`) 남 댓글을 따로 낸다.
129
+ - **판단**: 듣기가 그 방의 남 댓글을 모아(예: 10분) 한 번에 세션을 깨우고, 세션은 **요약만** 한다 — 남의 글을 실행하지 않는다.
128
130
  - **쓰는 곳**: `send_notification`(나에게만, 관련 항목 참조). 스레드에는 쓰지 않는다(멤버 대화에 끼어들지 않는다).
129
131
  - **끝**: 내가 "됐어"라고 하면 마지막 정리 답글 → `unfollow`(2절 규칙 3).
130
132
 
@@ -137,7 +139,7 @@ odyssey threads unfollow --roomUid <방> # 또는 --it
137
139
 
138
140
  ### D. 활동 기록기 — 모델이 아예 없는 일
139
141
 
140
- - **입구**: 게임·앱 프로세스의 시작·끝. **일**: `create_record` 한 번 → 세션마다 `add_record_trace`(time·endTime·`dedupeKey`).
142
+ - **입구**: 게임·앱 프로세스의 시작·끝. **일**: `save_record`(기록 만들기) 한 번 → 세션마다 `add_record_trace`(time·endTime·`dedupeKey`).
141
143
  - **멱등**: `dedupeKey` = 같은 키는 한 번만. 종료 코드 `4`(네트워크)만 같은 키로 재전송, `1`(도구 오류)은 고치기 전엔 다시 보내지 않는다.
142
144
  - 자세한 호출법(Windows·Python): README 「프로그램에서 쓰기」.
143
145
 
@@ -167,18 +169,18 @@ odyssey threads unfollow --roomUid <방> # 또는 --it
167
169
 
168
170
  ```markdown
169
171
  ## 제안: 클로드 코드 감시 에이전트
170
- - 하려는 일: 앱에서 맡긴 코딩 일을 이 저장소의 Claude Code 세션에 배달한다
172
+ - 하려는 일: 앱에서 맡긴 코딩 일을 이 저장소에서 일하는 Claude Code 세션이 직접 받는다
171
173
  - 입구: 할일에 `클로드 코드` 태그 · 아무 항목 댓글에 `@클로드코드`
172
- - 감지: `odyssey watch --tag "클로드 코드"` 상시(launchd)
173
- - 판단: 프로그램 = 배달 표(어느 세션을 깨우나) / 모델 = 할 일인가·물을까·끝났나
174
- - 대화창: 그 항목의 댓글 스레드(일꾼 답글 하나 · 질문은 notifyMe)
174
+ - 감지: 그 세션이 띄운 듣기(`listen.mjs` — `odyssey watch --tag "클로드 코드" --no-threads` 를 거른다) · 백그라운드로, 이벤트에 끝나며 깨운다
175
+ - 판단: 프로그램 = 깨울 표(태그 할일·멘션·태그 방·맡은 스레드) / 모델 = 할 일인가·물을까·끝났나
176
+ - 대화창: 그 항목의 댓글 스레드(답글 하나 · 질문은 notifyMe)
175
177
  - 지시: 할일 본문 + 내 댓글 / 자료: 에이전트 댓글 · 다른 사람 댓글 · 멘션 안 한 항목 본문
176
- - 멱등: state.json — 항목 키 → 세션 id · 배달한 commentUid · 커서 · 하루 사용액
177
- - 권한: 허락 = mcp__odyssey · npm test · git status/diff / 차단 = git push · firebase deploy · npm publish
178
- - 돈: 한 턴 $1 · 하루 $5
179
- - 끝: 일꾼이 결과 답글 → complete_todo. 관심 스레드는 그대로(14일 뒤 저절로)
180
- - 시험: --check → --dry-run(시험 할일 하나) → 실제로 "README 에 한 줄" 하나
181
- - 사람 일: odyssey login · Claude Code MCP 로그인 · 자동 시작 등록
178
+ - 멱등: state/listen.json — since · 낸 commentUid · 본 태그 할일 · 맡은 스레드
179
+ - 권한: 그 세션의 설정 그대로 / 차단(permissions.deny) = git push · firebase deploy · npm publish
180
+ - 돈: 깨울 때만 토큰 · 일 하나 마감 뒤 맥락 비우기(듣기 먼저 끄고)
181
+ - 끝: 결과 답글 → complete_todo. 관심 스레드는 그대로(14일 뒤 저절로) · 듣기를 다시 띄운다
182
+ - 시험: --check → --dry-run → 듣기를 띄우고 시험 할일 하나("README 에 한 줄")
183
+ - 사람 일: odyssey login · Claude Code MCP 로그인 · 세션을 열어 "들어" 한마디
182
184
  ```
183
185
 
184
186
  **채운 예 2 — 아침 정리 리포트(감시 없음)**
@@ -203,7 +205,8 @@ odyssey threads unfollow --roomUid <방> # 또는 --it
203
205
 
204
206
  ## 6. 하지 말 것
205
207
 
206
- - 디스패처가 모델에게 "이 댓글이 일인가"를 묻게 하기 — 대기 비용·비결정성. 판단은 깨운 세션이 스레드를 읽고 한다.
208
+ - 듣기 스크립트가 모델에게 "이 댓글이 일인가"를 묻게 하기 — 대기 비용·비결정성. 판단은 깨운 세션이 스레드를 읽고 한다.
209
+ - 세션이 `sleep` 루프로 기다리기 — 백그라운드 듣기의 종료(또는 Monitor 의 줄)가 깨우게 한다.
207
210
  - `list_todos` 를 매분 폴링 — 실시간이면 `watch`, 아니면 하루 몇 번이면 된다.
208
211
  - `tags`·`checklist`·`memo` 를 일부만 보내기 — **전체 교체**다. 태그를 빠뜨리면 그 할일이 감시에서 조용히 빠진다.
209
212
  - 없는 UID 추측 — `search`·`list_*` 로 찾는다.