refactor: gpt 스트림 오류 최소화

2026-09-17 15:34:01 +09:00
parent d7ceca39a0
commit 0a8c8e55a8
11 changed files with 957 additions and 29 deletions
@@ -0,0 +1,57 @@
+# Managed Task Tools Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Add recoverable, compact-output managed task tools for long-running Coka MCP commands.
+
+**Architecture:** Add a `ManagedTaskManager` facade on top of the existing `ProcessManager`. Extend process startup with an internal output observer so managed tasks can persist complete output without changing low-level tool responses, then register four additive MCP tools.
+
+**Tech Stack:** Node.js 22+, TypeScript, MCP SDK, Zod, Vitest.
+
+**Spec:** `docs/superpowers/specs/2026-09-17-managed-task-tools-design.md`
+
+## Global Constraints
+
+- Preserve all existing low-level process tools and semantics.
+- Do not execute the same retained managed task twice when the same task key, command, and cwd are supplied.
+- Store full managed-task output on disk while keeping MCP responses bounded.
+- Recovery must work by stable task key after a response-stream interruption.
+
+---
+
+### Task 1: Managed task core
+
+**Files:**
+- Create: `src/managed-task-manager.ts`
+- Modify: `src/process-manager.ts`
+- Test: `test/managed-task-manager.test.ts`
+
+- [x] Write failing tests for reuse, compact summaries/full logs, restart, cancellation, and recovery listing.
+- [x] Run the focused test and verify RED.
+- [x] Add the smallest ProcessManager output-observer seam and ManagedTaskManager implementation.
+- [x] Run the focused test and verify GREEN.
+
+### Task 2: MCP tool surface
+
+**Files:**
+- Create: `src/managed-task-tools.ts`
+- Modify: `src/mcp-server.ts`
+- Modify: `test/tool-metadata.test.ts`
+- Modify: `test/all-tools.integration.test.ts`
+
+- [x] Update inventory/metadata tests first and verify RED.
+- [x] Register `start_managed_task`, `read_managed_task`, `list_managed_tasks`, and `cancel_managed_task`.
+- [x] Exercise start/reuse/read/list/cancel through MCP integration tests.
+- [x] Verify focused tests GREEN.
+
+### Task 3: Documentation and regression verification
+
+**Files:**
+- Modify: `README.md`
+- Create: `AGENTS.md`
+
+- [x] Document the high-level managed-task workflow and recovery behavior.
+- [x] Run `npm test`.
+- [x] Run `npm run typecheck`.
+- [x] Run `npm run build`.
+- [x] Run `git diff --check` and inspect the final diff.
@@ -0,0 +1,26 @@
+# Managed Task Tools Design
+
+## Goal
+
+Make long-running Coka MCP work resilient to ChatGPT response-stream interruption while reducing tool-call count and response payload size.
+
+## Design
+
+Keep the existing `ProcessManager` and all low-level process tools intact. Add a `ManagedTaskManager` facade that owns stable task keys, writes the complete process output to a log file, returns bounded summaries, and maps task keys back to process session IDs.
+
+A managed task is identified by a caller-supplied `taskKey`. Calling start again with the same key and same command/cwd reuses the retained task instead of executing it twice. A completed task may be explicitly restarted. Reusing a key for a different command/cwd is rejected unless the prior task has completed and an explicit restart is requested.
+
+## MCP tools
+
+- `start_managed_task`: start or safely reuse a non-interactive long-running shell command. Wait only for a small initial interval, then return compact state.
+- `read_managed_task`: optionally long-poll a task and return compact state, important lines, and a bounded log tail.
+- `list_managed_tasks`: list recoverable running/recent tasks by stable task key.
+- `cancel_managed_task`: terminate a running managed task using the existing process-tree termination semantics.
+
+## Log behavior
+
+Full stdout and stderr are appended to a per-task log beneath the configured managed-task log directory. The MCP result never returns the full log by default. It returns a bounded tail plus selected important lines captured across the full output stream (errors, failures, warnings, successful/failed build markers, and common test summaries), so early failures are not lost when later output pushes them outside the tail.
+
+## Compatibility
+
+Existing `exec_command`, `run_script`, `read_process`, `write_stdin`, `terminate_process`, and `list_processes` behavior remains unchanged. Managed-task functionality is additive.