개선: Machine 첫 결과 의미 통일

initializer와 doctor가 machine.run 기반 구조화 행동을 네 adapter에 동일하게 제공한다.

JavaScript와 Python doctor API가 complete preflight와 blocking report를 보존한다.

검증: npm test, npm run test:package, npm run test:control-product, npm run test:mcp-product
npm run test:python-sdk, npm run test:types

Author: eddmpython

README.ko.md

@@ -111,6 +111,8 @@ Machine image 계약을 사용한다.
 지원 JavaScript client는 `pyproc/control`의 `PyProcControlClient`를 사용하고, 언어 중립 NDJSON 연결은
 설치된 `pyproc-control` 명령을 사용한다. 두 경로는 같은 strict manifest, operation catalog, 취소 규칙,
 검증된 attachment framing을 사용한다.
+Effect-free doctor는 `machine.run`을 정본 의미로 고정하고 shell, JavaScript, Python, MCP에 매핑한 하나의
+구조화된 첫 결과 행동도 반환한다.
 
 [Machine Entrance](skills/use-pyproc-machine/references/machine-entrance.md)에서 시작한 뒤
 [JavaScript Control SDK](skills/control-pyproc/references/javascript-control.md),

README.md

@@ -131,6 +131,8 @@ contract as root `boot()` and `open()`.
 Use `PyProcControlClient` from `pyproc/control` for a supported JavaScript client, or the installed
 `pyproc-control` command for a language-neutral NDJSON connection. Both use the same strict manifest,
 operation catalog, cancellation rules, and verified attachment framing.
+The effect-free doctor also returns one structured first-result action mapped to shell, JavaScript, Python, and
+MCP, with `machine.run` as the canonical meaning.
 
 Start with [Machine Entrance](skills/use-pyproc-machine/references/machine-entrance.md), then use the
 [JavaScript Control SDK](skills/control-pyproc/references/javascript-control.md), the

mainPlan/9-agentComputerStandardReadiness/README.md

@@ -1,6 +1,6 @@
 # Initiative 9: agent computer와 웹 표준 후보 준비도
 
-상태: **진행 중, M0 완료, M1 두 하위 계약 완료**
+상태: **진행 중, M0과 M1 완료, M2 다음 작업**
 
 이 문서는 agent가 pyproc에 들어와 보고, 행동하고, 계산하고, 세션을 넘겨 계속 일하는 전 과정을
 제품 기준으로 끌어올리는 실행 원장이다. 기존 능력 점수와 증거의 정본은
@@ -14,7 +14,7 @@
 
 | 질문 | 현재 판정 | 실사용 증거 | 완성까지 남은 것 |
 |---|---|---|---|
-| agent 진입점 | 강함, 완성 아님 | exact install 뒤 `pythonOnly` init, effect-free doctor, CPython 실행이 공개 명령으로 완결되고 현재 main은 package engine을 자동 선택 | client별 다음 명령 의미 통일 |
+| agent 진입점 | 매우 강함, 장기 수명주기 검증은 계속 | exact install 뒤 package engine 자동 선택, effect-free doctor, 네 adapter의 같은 CPython 첫 결과가 공개 계약으로 완결 | M2의 반복 작업과 정리 수명주기 |
 | 눈과 팔 | 강함, 완성 아님 | APX Situation이 링크를 식별하고 proof-carrying click 뒤 `Smallest start` 출현을 confirmed로 봉인. 현재 main은 첫 문서 교체를 effect 재시도 없이 수렴 | 장기 반복 수명주기와 실제 GPU visual oracle 확대 |
 | 비-agent 컴퓨팅 몸체 | 훌륭한 브라우저 컴퓨터, 로컬 OS 완전 대체는 아님 | owned CPython, worker process, OPFS disk, checkpoint, Machine image, Python과 x86 guest gate | 임의 native wheel, shared-memory thread, wasm 도구층, Node guest, quota 축출 계약 |
 | 단독 자립성 | Python 기본 Machine은 높음, 전체 WebComputer는 미완성 | source-built CPython과 stdlib가 npm에 포함되고 기본 부팅의 제3자 요청은 0 | x86 emulator와 firmware의 독립 재현, GPU 실기 CI, 브라우저 범위 확대 |
@@ -69,13 +69,15 @@ implementation experience는 독립적이고 상호운용 가능한 구현, 저
 
 ### M1. Machine Entrance 첫 결과 수렴
 
-판정: **진행 중**
+판정: **완료**
 
 - 완료: exact version 설치 뒤 engine 경로를 사람이 조립하지 않아도 package-owned CPython을 선택한다.
   명시한 `--engine-root`만 override로 사용하며 결과와 생성 README에 선택 출처와 절대 경로를 남긴다.
 - 완료: COI bootstrap의 첫 문서 교체를 관찰하고 같은 typed focus의 새 capability를 한 번 재발급한다.
   `notSent` 외에는 재시도하지 않고, 유일성이나 권한이 달라지거나 두 번째 교체가 생기면 중단한다.
-- doctor의 다음 명령이 shell, JavaScript, Python, MCP에서 같은 의미를 가진다.
+- 완료: initializer와 doctor가 같은 구조화된 `next.firstResult`를 반환한다. 부모 의미는
+  `machine.run`과 한 입력으로 고정하고 shell argument vector, JavaScript와 Python SDK method, MCP tool을
+  adapter로 둔다.
 
 첫 하위 계약 증거:
 
@@ -85,9 +87,16 @@ implementation experience는 독립적이고 상호운용 가능한 구현, 저
 - 첫 문서 교체 probe는 수정 전 stale locator와 effect 0을 재현했고, 수정 후 postcondition confirmed와
   effect 정확히 1회로 수렴했다. 설치 MCP 제품 gate도 같은 여정을 고정한다.
 - browser control, 3회 48-action stress, APX 11개 실브라우저 게이트가 GREEN이다.
+- `PyProcControlClient.doctor()`와 `PyProcClient.doctor()`는 complete doctor와 representable blocking report를
+  그대로 반환한다. 기존 `check()`는 startup compatibility surface로 유지한다.
+- packed install에서 doctor가 준 exact shell arguments, JavaScript method, Python method, MCP tool이 모두
+  canonical `machine.run`으로 42를 반환했다. Control 23개, MCP 22개, Python wheel과 sdist 5개 제품 gate가
+  GREEN이다.
 
 ### M2. Eyes와 Arms 장기 수명주기
 
+판정: **다음 작업**
+
 - 반복 Situation, screenshot, proof-carrying action, artifact cleanup에서 handle과 process 잔류 0을 증명한다.
 - stale, ambiguous, occluded, navigation 교체를 wrong effect 없이 자동 수렴시키는 상한을 고정한다.
 - hardware GPU runner에서 pixel 결과 oracle을 추가해 수동 증거 상한을 제거한다.

pythonSdk/src/pyprocControl/client.py

@@ -179,12 +179,34 @@ def start(cls, configPath: str | os.PathLike[str], *,
     def check(cls, configPath: str | os.PathLike[str], *,
               command: str | os.PathLike[str] | Sequence[str | os.PathLike[str]] | None = None,
               timeout: float = 30.0) -> dict[str, Any]:
-        args = [*resolvedCommand(command), "--config", str(Path(configPath).resolve()), "--check"]
-        completed = subprocess.run(args, text=True, encoding="utf-8", errors="strict",
-                                   capture_output=True, timeout=timeout, check=True)
-        report = json.loads(completed.stdout)
+        return cls._entranceReport(configPath, command=command, timeout=timeout, mode="check")
+
+    @classmethod
+    def doctor(cls, configPath: str | os.PathLike[str], *,
+               command: str | os.PathLike[str] | Sequence[str | os.PathLike[str]] | None = None,
+               timeout: float = 30.0) -> dict[str, Any]:
+        return cls._entranceReport(configPath, command=command, timeout=timeout, mode="doctor")
+
+    @classmethod
+    def _entranceReport(cls, configPath: str | os.PathLike[str], *,
+                        command: str | os.PathLike[str] | Sequence[str | os.PathLike[str]] | None,
+                        timeout: float, mode: str) -> dict[str, Any]:
+        config = str(Path(configPath).resolve())
+        entrance = ["doctor", "--config", config] if mode == "doctor" else ["--config", config, "--check"]
+        completed = subprocess.run([*resolvedCommand(command), *entrance], text=True, encoding="utf-8",
+                                   errors="strict", capture_output=True, timeout=timeout, check=False)
+        try:
+            report = json.loads(completed.stdout)
+        except json.JSONDecodeError as error:
+            completed.check_returncode()
+            raise RuntimeError(f"pyproc-control {mode} did not return JSON") from error
+        if mode == "doctor" and isinstance(report, dict) and isinstance(report.get("ok"), bool):
+            if report["ok"] != (completed.returncode == 0):
+                raise RuntimeError("pyproc-control doctor exit and report disagree")
+            return report
+        completed.check_returncode()
         if not isinstance(report, dict) or report.get("ok") is not True:
-            raise RuntimeError("pyproc-control preflight did not return an ok report")
+            raise RuntimeError(f"pyproc-control {mode} did not return an ok report")
         return report
 
     @property

scripts/controlProtocol/controlApi.d.ts

@@ -21,6 +21,50 @@ export interface MachineRunOutput {
   readonly value: string | null;
 }
 
+export interface MachineFirstResult {
+  readonly schemaVersion: 1;
+  readonly operation: "machine.run";
+  readonly input: Readonly<{ readonly code: string }>;
+  readonly shell: Readonly<{ readonly command: "pyproc-control"; readonly arguments: readonly string[] }>;
+  readonly javascript: Readonly<{
+    readonly module: "pyproc/control";
+    readonly client: "PyProcControlClient";
+    readonly startMethod: "start";
+    readonly startArguments: readonly string[];
+    readonly method: "runPython";
+    readonly arguments: readonly string[];
+  }>;
+  readonly python: Readonly<{
+    readonly module: "pyprocControl";
+    readonly client: "PyProcClient";
+    readonly startMethod: "start";
+    readonly startArguments: readonly string[];
+    readonly method: "runPython";
+    readonly arguments: readonly string[];
+  }>;
+  readonly mcp: Readonly<{
+    readonly command: "pyproc-mcp";
+    readonly serverArguments: readonly string[];
+    readonly tool: "pythonRun";
+    readonly arguments: Readonly<{ readonly code: string }>;
+  }>;
+}
+
+export interface MachineDoctorReport extends Readonly<Record<string, unknown>> {
+  readonly ok: boolean;
+  readonly configPath: string;
+  readonly checks: readonly Readonly<Record<string, unknown>>[];
+  readonly blocking: readonly Readonly<Record<string, unknown>>[];
+  readonly advisory: readonly Readonly<Record<string, unknown>>[];
+  readonly next: Readonly<{
+    readonly doctor: string;
+    readonly start: string;
+    readonly run: string;
+    readonly mcp: string;
+    readonly firstResult: MachineFirstResult;
+  }>;
+}
+
 export interface MachineImageOutput {
   readonly kind: "machineImage";
   readonly mimeType: "application/x-pymachine";
@@ -863,6 +907,8 @@ export class PyProcControlClient {
   static start(configPath: string, options?: ControlProcessOptions): Promise<PyProcControlClient>;
   static check(configPath: string, options?: ControlProcessOptions & { readonly timeoutMs?: number }):
     Promise<Readonly<Record<string, unknown>>>;
+  static doctor(configPath: string, options?: ControlProcessOptions & { readonly timeoutMs?: number }):
+    Promise<MachineDoctorReport>;
   readonly ready: Promise<this>;
   readonly operations: readonly string[];
   readonly diagnostics: string;

scripts/controlProtocol/controlApi.js

@@ -65,10 +65,12 @@ async function waitForExit(child, timeoutMs) {
   await exited;
 }
 
-async function runCheck(configPath, options) {
+async function runEntranceReport(configPath, options, mode) {
   const command = controlCommand(options.command);
-  const timeoutMs = positiveTimeout(options.timeoutMs, "control check timeoutMs", DEFAULT_STARTUP_TIMEOUT_MS);
-  const child = spawn(command[0], [...command.slice(1), "--config", controlConfigPath(configPath), "--check"], {
+  const timeoutMs = positiveTimeout(options.timeoutMs, `control ${mode} timeoutMs`, DEFAULT_STARTUP_TIMEOUT_MS);
+  const args = mode === "doctor" ? ["doctor", "--config", controlConfigPath(configPath)]
+    : ["--config", controlConfigPath(configPath), "--check"];
+  const child = spawn(command[0], [...command.slice(1), ...args], {
     cwd: options.cwd || process.cwd(), env: options.env || process.env, windowsHide: true,
     stdio: ["ignore", "pipe", "pipe"],
   });
@@ -86,19 +88,36 @@ async function runCheck(configPath, options) {
   if (outcome.state === "timeout") {
     child.kill("SIGTERM");
     await waitForExit(child, DEFAULT_SHUTDOWN_TIMEOUT_MS);
-    throw timeoutError("pyproc-control preflight timed out");
+    throw timeoutError(`pyproc-control ${mode} timed out`);
   }
   const { code, signal } = unwrap(outcome);
-  if (code !== 0) throw new Error(`pyproc-control preflight failed (${code ?? signal})\n${stderr}`);
-  let report;
+  let report = null;
   try { report = JSON.parse(stdout); }
-  catch (error) { throw new Error("pyproc-control preflight did not return JSON", { cause: error }); }
+  catch (error) {
+    if (code !== 0) throw new Error(`pyproc-control ${mode} failed (${code ?? signal})\n${stderr}`);
+    throw new Error(`pyproc-control ${mode} did not return JSON`, { cause: error });
+  }
+  if (mode === "doctor" && report && typeof report === "object" && typeof report.ok === "boolean") {
+    if (report.ok !== (code === 0)) {
+      throw new Error(`pyproc-control doctor exit and report disagree (${code ?? signal})`);
+    }
+    return Object.freeze(report);
+  }
+  if (code !== 0) throw new Error(`pyproc-control ${mode} failed (${code ?? signal})\n${stderr}`);
   if (!report || typeof report !== "object" || report.ok !== true) {
-    throw new Error("pyproc-control preflight did not return an ok report");
+    throw new Error(`pyproc-control ${mode} did not return an ok report`);
   }
   return Object.freeze(report);
 }
 
+function runCheck(configPath, options) {
+  return runEntranceReport(configPath, options, "check");
+}
+
+function runDoctor(configPath, options) {
+  return runEntranceReport(configPath, options, "doctor");
+}
+
 export { ControlRemoteError } from "./controlClient.js";
 export { ExecutionMemoryRegistry, createExecutionMemoryRegistry }
   from "../executionMemory/executionMemoryRegistry.js";
@@ -439,6 +458,10 @@ export class PyProcControlClient extends ControlStdioClient {
     return runCheck(configPath, options);
   }
 
+  static doctor(configPath, options = {}) {
+    return runDoctor(configPath, options);
+  }
+
   requestAsync(operation, input = {}, { requestId, spaceId } = {}) {
     const id = requestId || `request:${++this._sequence}`;
     const result = super.request(operation, input, { requestId: id, spaceId });

scripts/machineEntrance/machineDoctor.js

@@ -10,6 +10,7 @@ import { CONTROL_PYTHON_TOOLS } from "../controlProtocol/controlProduct.mjs";
 import { controlOperationCatalog } from "../controlProtocol/controlOperations.js";
 import { loadMcpProductConfig } from "../mcpProductConfig.mjs";
 import { inspectEngineDistribution } from "./engineInspection.js";
+import { createMachineNext } from "./machineNext.js";
 import { verifyWindowsNativeInstallation } from "../actuation/windowsNativeHost.js";
 
 const PACKAGE_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..", "..");
@@ -18,14 +19,6 @@ function check(code, severity, explanation, details = {}) {
   return Object.freeze({ code, severity, explanation, ...details });
 }
 
-function safeNext(configPath) {
-  return Object.freeze({
-    doctor: `pyproc-control doctor --config "${configPath}"`,
-    start: `pyproc-control --config "${configPath}"`,
-    run: `pyproc-control run --config "${configPath}" --code "40 + 2"`,
-  });
-}
-
 async function installedVersion(packageRoot) {
   const value = JSON.parse(await readFile(join(packageRoot, "package.json"), "utf8"));
   if (typeof value.version !== "string") throw new Error("installed package version is unavailable");
@@ -49,6 +42,11 @@ async function automationFacts(loaded) {
     enabled: true,
     provider,
     cdpEndpoint: provider === "nativeCdp",
+    allowedOrigins: loaded.browserControl.targetOrigins,
+    actions: loaded.browserControl.actions,
+    rawMethods: loaded.browserControl.rawMethods,
+    maxRisk: loaded.browserControl.maxRisk,
+    artifacts: loaded.browserControl.artifacts,
     operations: controlOperationCatalog(tools).map((entry) => entry.name),
     ...(replay ? { replay: Object.freeze({ recordingId: replay.recordingId, entries: replay.entries.length,
       finalSha256: replay.finalSha256, sourceProvider: replay.provider.providerKind }) } : {}),
@@ -72,7 +70,7 @@ export async function inspectMachineProfile(configPath, {
     }));
     return Object.freeze({ ok: false, configPath: resolvedConfig, checks: Object.freeze(checks),
       blocking: Object.freeze(checks.filter((entry) => entry.severity === "blocking")),
-      advisory: Object.freeze([]), next: safeNext(resolvedConfig) });
+      advisory: Object.freeze([]), next: createMachineNext(resolvedConfig) });
   }
 
   try {
@@ -152,6 +150,6 @@ export async function inspectMachineProfile(configPath, {
     advisory: Object.freeze(advisory),
     automation,
     windowsNative,
-    next: safeNext(loaded.configPath),
+    next: createMachineNext(loaded.configPath),
   });
 }

scripts/machineEntrance/machineNext.js

@@ -0,0 +1,60 @@
+// machineNext.js - 한 Machine 첫 결과를 모든 공개 adapter의 같은 operation으로 표현한다.
+import { resolve } from "node:path";
+import { controlOperationForTool } from "../controlProtocol/controlOperations.js";
+
+const FIRST_RESULT_CODE = "40 + 2";
+const MCP_RUN_TOOL = "pythonRun";
+
+function frozenArray(values) {
+  return Object.freeze([...values]);
+}
+
+export function createMachineNext(configPath) {
+  if (typeof configPath !== "string" || !configPath) {
+    throw new TypeError("Machine next configPath must be a non-empty string");
+  }
+  const resolvedConfig = resolve(configPath);
+  const input = Object.freeze({ code: FIRST_RESULT_CODE });
+  const operation = controlOperationForTool(MCP_RUN_TOOL);
+  if (!operation) throw new Error(`Control operation is missing for ${MCP_RUN_TOOL}`);
+
+  const firstResult = Object.freeze({
+    schemaVersion: 1,
+    operation,
+    input,
+    shell: Object.freeze({
+      command: "pyproc-control",
+      arguments: frozenArray(["run", "--config", resolvedConfig, "--code", FIRST_RESULT_CODE]),
+    }),
+    javascript: Object.freeze({
+      module: "pyproc/control",
+      client: "PyProcControlClient",
+      startMethod: "start",
+      startArguments: frozenArray([resolvedConfig]),
+      method: "runPython",
+      arguments: frozenArray([FIRST_RESULT_CODE]),
+    }),
+    python: Object.freeze({
+      module: "pyprocControl",
+      client: "PyProcClient",
+      startMethod: "start",
+      startArguments: frozenArray([resolvedConfig]),
+      method: "runPython",
+      arguments: frozenArray([FIRST_RESULT_CODE]),
+    }),
+    mcp: Object.freeze({
+      command: "pyproc-mcp",
+      serverArguments: frozenArray(["--config", resolvedConfig]),
+      tool: MCP_RUN_TOOL,
+      arguments: input,
+    }),
+  });
+
+  return Object.freeze({
+    doctor: `pyproc-control doctor --config "${resolvedConfig}"`,
+    start: `pyproc-control --config "${resolvedConfig}"`,
+    run: `pyproc-control run --config "${resolvedConfig}" --code "${FIRST_RESULT_CODE}"`,
+    mcp: `pyproc-mcp --config "${resolvedConfig}"`,
+    firstResult,
+  });
+}

scripts/machineEntrance/profileInitializer.js

@@ -4,6 +4,7 @@ import { access, lstat, mkdir, readFile, realpath, rename, rm, writeFile } from
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
 import { compileMachineProfile } from "./machineProfile.js";
+import { createMachineNext } from "./machineNext.js";
 
 export const MACHINE_PROFILE_DIRECTORY = ".pyproc";
 export const MACHINE_PROFILE_FILES = Object.freeze(["manifest.json", "client.json", "README.md"]);
@@ -184,10 +185,6 @@ export async function initializeMachineProfile({
     readmePath: join(paths.output, "README.md"),
     dryRun,
     overwritten: overwrite && present.length > 0,
-    next: Object.freeze({
-      doctor: `pyproc-control doctor --config "${join(paths.output, "manifest.json")}"`,
-      run: `pyproc-control run --config "${join(paths.output, "manifest.json")}" --code "40 + 2"`,
-      mcp: `pyproc-mcp --config "${join(paths.output, "manifest.json")}"`,
-    }),
+    next: createMachineNext(join(paths.output, "manifest.json")),
   });
 }