@asc-agent/runtime 0.2.0 → 0.2.1

package/README.md

@@ -7,7 +7,7 @@ proceed-by-default, escalation, audit, the external-write guard, host integratio
 here.
 
 ```bash
-npm install -g @asc-agent/runtime@0.2.0
+npm install -g @asc-agent/runtime@0.2.1
 ```
 
 npm owns the executable link (on Windows, npm's own `asc.cmd`). This package never edits

package/dist/adapters/claude-code/skill.js

@@ -13,6 +13,10 @@
 // 몫이고, skill에 복제되는 순간 두 곳이 서로 다른 정책을 말하기 시작한다.
 // skill이 정하는 것은 다섯뿐이다 — 언제 어떤 표면을 부르는가 / 무엇을 모으는가 /
 // 무엇을 직접 판단하면 안 되는가 / depth를 언제 올리는가 / 언제 돌려주는가.
+// 버전은 **한 곳에서만** 온다. 손으로 적으면 릴리스마다 여기가 뒤처지고, 이 문자열은
+// 사용자의 `~/.claude/skills/` 에 실제로 쓰이므로 그 지연이 사용자의 명령이 된다 —
+// 0.2.0 회차에 이 파일이 `@0.1.0` 을 들고 있었다.
+import { BOOTSTRAP_SPEC } from "../../core/distribution/release.js";
 /** 설치 단위. 파일이 늘어도 manifest 기반 설치·제거 계약은 그대로다 (C-05 §5). */
 export function skillBundle() {
     return [
@@ -45,8 +49,12 @@ The user does not need to know this sequence. This is the one the skill follows.
 \`\`\`text
 0. Is ASC even installed? If \`asc\` is not on PATH, this machine has no runtime yet.
      Start from the bootstrap, not from \`asc\`:
-       npx --yes @asc-agent/bootstrap@0.1.0 setup --agent
+       npx --yes ${BOOTSTRAP_SPEC} setup apply --json
      Its JSON carries \`actions[].portable\` — run that, never \`display\`.
+     If the host refuses to run that command at all, that is a permission boundary, not an
+     ASC failure. Do not try other shapes of the same thing. Show the person the exact
+     command and ask them to switch this session's permission mode so they can approve the
+     single run — a standing allow rule for the command was measured and did not work.
 
 1. Attached?              asc setup status
      not yet  → asc init (it shows profile candidates; a person chooses)

package/dist/cli/asc.d.ts

@@ -6,4 +6,10 @@
  * 설치하는 것은 말이 안 되고, 그것을 계획에 넣으면 매 setup이 npm을 부른다.
  */
 export type AscEntry = 'runtime' | 'bootstrap';
+/**
+ * bootstrap이 자기 USAGE에 적을 값. **거기서 손으로 적지 않게 하려고 내보낸다** —
+ * 두 패키지가 각자 버전 문자열을 들면 릴리스마다 한쪽이 뒤처지고, 그 지연은 곧
+ * 사용자가 실행하는 명령이 된다 (0.2.0 회차의 skill.ts가 그랬다).
+ */
+export { BOOTSTRAP_SPEC } from '../core/distribution/release.ts';
 export declare function runAscCommand(argv: string[], entry?: AscEntry): Promise<number>;

package/dist/cli/asc.js

@@ -8,11 +8,12 @@
 // 읽기 전용이다. 결정 제출은 사람의 명시적 의사표현을 받는 별도 경로로 나간다 (B-06).
 import { execFile, spawnSync } from 'node:child_process';
 import { parseArgs, promisify } from 'node:util';
-import { existsSync, realpathSync } from 'node:fs';
+import { existsSync, readdirSync, realpathSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import { fileURLToPath } from 'node:url';
 import { homedir } from 'node:os';
 import { basename, dirname, join, resolve } from 'node:path';
+import { MINIMUM_NODE_MAJOR, checkNodeRuntime, } from "../core/distribution/node-runtime.js";
 import { GitHubClient, discoverToken } from "../adapters/github/client.js";
 import { GitHubChangeContext, GitHubInventory, GitHubResourceContext } from "../adapters/github/context.js";
 import { GitHubEventSource } from "../adapters/github/event-source.js";
@@ -123,7 +124,7 @@ const USAGE = `asc — Agent Session Control
   asc setup plan   [--profile <id>] [--scope local|project] [--json]
                         # says what it would change — changes nothing
   asc setup apply  [--profile <id>] [--scope local|project] [--json]
-  asc setup --agent     # non-interactive apply. stdout is a single JSON document
+  asc setup apply --json   # non-interactive apply. stdout is a single JSON document
 
   asc session issue <ID> --role <role> --goal <text> [--block <id>]
                          [--parent <S-ID>] [--issued-by <principal>]
@@ -297,6 +298,12 @@ const DECISION_ERROR = {
     ALREADY_DECIDED: '이미 결정된 요청이다.',
     STALE: '읽은 뒤 요청이 바뀌었다. 다시 확인하고 결정하라.',
 };
+/**
+ * bootstrap이 자기 USAGE에 적을 값. **거기서 손으로 적지 않게 하려고 내보낸다** —
+ * 두 패키지가 각자 버전 문자열을 들면 릴리스마다 한쪽이 뒤처지고, 그 지연은 곧
+ * 사용자가 실행하는 명령이 된다 (0.2.0 회차의 skill.ts가 그랬다).
+ */
+export { BOOTSTRAP_SPEC } from "../core/distribution/release.js";
 /**
  * CLI 한 번의 실행. **다른 진입도 이 함수를 부른다** (C-14 불변식 ①).
  *
@@ -332,6 +339,54 @@ function explainConfigError(error) {
         return `That profile is not valid JSON — ${error.message}`;
     return null;
 }
+/** 실제 파일시스템·프로세스를 물린다. Core는 이 중 아무것도 직접 하지 않는다. */
+function nodeRuntimeDeps() {
+    return {
+        version: process.version,
+        exists: (path) => existsSync(path),
+        list: (path) => {
+            try {
+                return readdirSync(path);
+            }
+            catch {
+                // 없는 디렉터리는 "후보 없음"이다. 이 machine에 그 배치가 없을 뿐이다.
+                return [];
+            }
+        },
+        run: nodeProcessRunner,
+        home: homedir(),
+        join,
+    };
+}
+/**
+ * 못 돌린다는 사실과, 이 machine에서 실제로 쓸 수 있는 것을 함께 준다.
+ *
+ * 후보가 있으면 **같은 canonical 명령을 그 Node로 돌리는 형태**를 낸다 — 이것은 per-invocation
+ * 환경변수이지 PATH·profile 수정이 아니다 (불변식 ⑰). 이 형태마저 host가 실행을 거부하면
+ * 그때는 ASC의 문제가 아니라 host 경계이며, AGENTS.md가 그 자리를 정의한다.
+ */
+function reportNodeRuntime(check, asJson) {
+    const actions = check.candidates.map((candidate) => ({
+        type: 'use_node_runtime',
+        display: `PATH="${dirname(candidate.path)}:$PATH" ${shorthandCommand(['setup', 'apply', '--json'])}`,
+        portable: `PATH="${dirname(candidate.path)}:$PATH" ${portableCommand(['setup', 'apply', '--json'])}`,
+        node: candidate,
+    }));
+    if (asJson) {
+        console.log(JSON.stringify({
+            code: check.code,
+            detail: check.detail,
+            runtime: { node: process.execPath, version: check.version, required: `>=${MINIMUM_NODE_MAJOR}` },
+            candidates: check.candidates,
+            nextActions: actions.map((action) => action.portable),
+            actions,
+        }, null, 2));
+        return;
+    }
+    console.error(check.detail);
+    for (const action of actions)
+        console.error(`  ${action.node.version} at ${action.node.path}\n    ${action.display}`);
+}
 export async function runAscCommand(argv, entry = 'runtime') {
     const { values, positionals } = parseArgs({
         args: argv,
@@ -437,6 +492,17 @@ export async function runAscCommand(argv, entry = 'runtime') {
         console.log(USAGE);
         return 0;
     }
+    // **지원 하한을 먼저 답한다** (C-14 §3). `engines` 는 npm에게 하는 말이라 기본값에서
+    // 경고로만 나가고, 그러면 "경고 뒤에 그래도 돌아감"이 된다 — 사용자는 자기가 지원
+    // 범위 안인지 끝내 모른다. 여기서 한 번, 결정적으로 답한다.
+    //
+    // 이 자리인 이유: 설치된 `asc` 와 bootstrap이 **같은 문으로 들어온다**. bootstrap에
+    // 두면 그쪽에 정책이 생기고(C-14 불변식 ⑦), 그러면 두 진입의 답이 갈릴 수 있다.
+    const runnable = await checkNodeRuntime(nodeRuntimeDeps());
+    if (!runnable.ok) {
+        reportNodeRuntime(runnable, Boolean(values.json) || Boolean(values.agent));
+        return 1;
+    }
     // 선택된 build로 넘길 것이 있으면 여기서 넘긴다. **선택 자체를 다루는 명령은 넘기지
     // 않는다** — 잘못 가리키는 선택을 고치거나 들여다보는 명령이 그 선택 때문에 못 돌면
     // 사람이 갇힌다.
@@ -920,7 +986,7 @@ function declaredPolicies(resolved) {
     }
     return declared;
 }
-const ASC_VERSION = '0.2.0';
+const ASC_VERSION = '0.2.1';
 const CAPABILITIES = ['scm.github', 'state.markdown', 'approval.local'];
 const ADAPTER_VERSIONS = { 'scm.github': ASC_VERSION, 'state.markdown': ASC_VERSION };
 /**
@@ -1050,6 +1116,7 @@ async function detectSetupState(values, entry) {
     const scope = values.scope === 'project' ? 'project' : 'local';
     const hostReport = await verifyInstall(defaultPaths());
     return {
+        entry,
         projectRoot,
         git,
         ...(ascRoot ? { ascRoot } : {}),
@@ -1293,10 +1360,12 @@ async function runProfileAdopt(values, entry) {
     // 다음 한 걸음은 두 형태로 준다 — agent는 portable, 사람은 display (C-14 불변식 ⑯).
     // 여기서는 설치 상태를 다시 관측하지 않는다: 이 명령이 도는 방식이 곧 그 답이다.
     const args = ['setup', 'apply', '--profile', adopted.id];
+    // portable은 agent가 그대로 실행한다 — 기계가 읽는 형태로 끝난다 (setup-plan.ts와 같은 규칙).
+    const machine = [...args, '--json'];
     const action = {
         type: 'apply_setup',
         display: shorthandCommand(args),
-        portable: entry === 'bootstrap' ? portableCommand(args) : shorthandCommand(args),
+        portable: entry === 'bootstrap' ? portableCommand(machine) : shorthandCommand(machine),
     };
     if (asJson) {
         console.log(JSON.stringify({ id: adopted.id, path, project: parsed.data.project, warnings: adopted.warnings, nextActions: [action.portable], actions: [action] }, null, 2));

package/dist/core/attach/setup-plan.d.ts

@@ -1,6 +1,15 @@
 import type { StableInstallState } from '../distribution/runtime-install.ts';
 /** 세상의 스냅샷. 읽기만 해서 만든다. */
 export type SetupState = {
+    /**
+     * 이 판단이 **어느 실행물 안에서** 나오는가 (C-14 §3.4).
+     *
+     * `runtime` 이면 지금 도는 것이 곧 설치된 `asc` 다 — 그 사실은 관측할 것이 아니라
+     * 이미 아는 것이다. 예전에는 이 축이 없어 `stableRuntime` 의 부재를 "설치 안 됨"으로
+     * 읽었고, 그래서 설치된 `asc` 가 자기를 bootstrap이라고 말하며 agent에게 `npx …` 를
+     * 돌려줬다 (v0.2.0 registry 관측). 진입점 자체가 이미 답의 일부다.
+     */
+    entry: 'runtime' | 'bootstrap';
     projectRoot: string;
     git: boolean;
     /** 이미 붙어 있으면 그 runtime 뿌리. 없으면 안 붙은 것이다. */

package/dist/core/attach/setup-plan.js

@@ -22,11 +22,22 @@ export function computeSetupPlan(state) {
     ];
     // 지금 명령이 어디서 도는가. 설치된 `asc` 가 없으면 bootstrap이고, 그때 agent에게
     // `asc …` 를 실행하라고 주면 안 된다 (C-14 §3.4 · 불변식 ⑯).
-    const mode = state.stableRuntime?.status === 'CURRENT' ? 'installed-runtime' : 'bootstrap';
-    const command = (args) => ({
-        display: shorthandCommand(args),
-        portable: mode === 'installed-runtime' ? shorthandCommand(args) : portableCommand(args),
-    });
+    //
+    // **진입점이 먼저다.** `asc` 로 들어왔다면 그 `asc` 는 이미 이 machine에 있다 — 그것을
+    // npm에게 물어볼 이유가 없다. bootstrap으로 들어왔을 때만 설치 축이 판정에 쓰인다.
+    const mode = state.entry === 'runtime' || state.stableRuntime?.status === 'CURRENT'
+        ? 'installed-runtime'
+        : 'bootstrap';
+    const command = (args) => {
+        // portable은 **agent가 그대로 실행하는 것**이므로 기계가 읽을 수 있는 형태로 끝나야
+        // 한다. `--json` 이 빠져 있으면 agent는 자기가 실행한 명령의 답을 산문으로 받는다 —
+        // "산문을 파싱하지 마라"고 적어 놓고 산문을 주는 꼴이었다. display는 사람 형태 그대로.
+        const machine = args.includes('--json') ? args : [...args, '--json'];
+        return {
+            display: shorthandCommand(args),
+            portable: mode === 'installed-runtime' ? shorthandCommand(machine) : portableCommand(machine),
+        };
+    };
     const changes = [];
     // stable runtime은 **프로젝트와도, profile 선택과도 무관하다.** 사람이 profile을
     // 고르는 중이어도 이 설치는 안전한 준비이고, 그것 때문에 통째로 WAIT 하지 않는다

package/dist/core/distribution/node-runtime.d.ts

@@ -0,0 +1,44 @@
+import type { ProcessRunner } from './runtime-install.ts';
+/** ASC가 요구하는 Node 하한. `engines` 와 같은 값이며 어긋나면 release:check가 잡는다. */
+export declare const MINIMUM_NODE_MAJOR = 24;
+export type NodeCandidate = {
+    path: string;
+    version: string;
+};
+export type NodeRuntimeCheck = {
+    ok: true;
+    version: string;
+} | {
+    ok: false;
+    code: 'NODE_RUNTIME_REQUIRED';
+    version: string;
+    detail: string;
+    /**
+     * 이 machine에서 찾은, 하한을 넘는 Node. **비어 있는 것이 실패가 아니다** —
+     * 그때는 Node를 놓는 일 자체가 사람의 경계다.
+     */
+    candidates: NodeCandidate[];
+};
+export type NodeRuntimeDeps = {
+    /** 지금 이 프로세스의 Node 버전 (`process.version` 형태: `v22.23.2`). */
+    version: string;
+    /** 후보 경로가 실제로 있는가. */
+    exists: (path: string) => boolean;
+    /** 디렉터리 목록. 없으면 빈 배열 — 없는 것은 오류가 아니다. */
+    list: (path: string) => string[];
+    /** `<node> -v` 를 돌린다. 실패는 후보 탈락일 뿐이다. */
+    run: ProcessRunner;
+    /** 사용자 홈. nvm 배치를 찾는 데만 쓴다. */
+    home: string;
+    /** 경로를 잇는다 — 호출자가 `node:path` 를 준다 (core는 파일시스템을 모른다). */
+    join: (...parts: string[]) => string;
+};
+/** `v22.23.2` · `22.23.2` 둘 다 받는다. 못 읽으면 `null` — 추측하지 않는다. */
+export declare function majorOf(version: string): number | null;
+/**
+ * 돌릴 수 있는가, 못 돌린다면 무엇이 있는가.
+ *
+ * 하한을 넘으면 **아무것도 하지 않는다** — 정상 경로에 I/O를 얹지 않는다. 못 넘을 때만
+ * 후보를 찾고, 후보에 대해서만 `-v` 를 묻는다.
+ */
+export declare function checkNodeRuntime(deps: NodeRuntimeDeps): Promise<NodeRuntimeCheck>;

package/dist/core/distribution/node-runtime.js

@@ -0,0 +1,75 @@
+// 이 프로세스를 돌리고 있는 Node가 ASC를 돌릴 수 있는가 (C-14 §3).
+//
+// **왜 판정이 필요한가**: `engines` 는 npm에게 하는 말이고, npm은 기본값에서 그것을
+// 경고로만 낸다. 그래서 Node 22에서 설치하면 "무서운 경고 한 줄 → 그래도 돌아감"이 되고,
+// 사용자는 자기가 지원 범위 안에 있는지 알 수 없다. 지원 하한은 결정적으로 답해야 한다.
+//
+// **여기서 하지 않는 것**: Node를 설치하지 않고, PATH·shell 설정을 고치지 않으며,
+// version manager를 다루지 않는다. 이미 이 machine에 있는 것을 **best-effort로 찾아
+// 알려 줄** 뿐이다 — 못 찾는 것은 정상이고, 그때는 사람이 답할 일이다.
+import { RELEASE_VERSION } from "./release.js";
+/** ASC가 요구하는 Node 하한. `engines` 와 같은 값이며 어긋나면 release:check가 잡는다. */
+export const MINIMUM_NODE_MAJOR = 24;
+/** `v22.23.2` · `22.23.2` 둘 다 받는다. 못 읽으면 `null` — 추측하지 않는다. */
+export function majorOf(version) {
+    const match = /^v?(\d+)\./.exec(version.trim());
+    return match ? Number(match[1]) : null;
+}
+/**
+ * 이미 있는 Node를 찾아본다. **탐색이지 관리가 아니다.**
+ *
+ * Homebrew와 nvm의 관례적 배치만 본다. 여기에 없다고 해서 Node가 없는 것은 아니고,
+ * 그 경우 후보 없이 돌려주는 것이 정직한 답이다 — 없는 것을 지어내지 않는다.
+ */
+function candidatePaths(deps) {
+    const found = [];
+    // Homebrew: /opt/homebrew/opt/node@26/bin/node · /usr/local/opt/node/bin/node
+    for (const prefix of ['/opt/homebrew/opt', '/usr/local/opt']) {
+        for (const entry of deps.list(prefix)) {
+            if (!/^node(@\d+)?$/.test(entry))
+                continue;
+            const path = deps.join(prefix, entry, 'bin', 'node');
+            if (deps.exists(path))
+                found.push(path);
+        }
+    }
+    // nvm: ~/.nvm/versions/node/v24.1.0/bin/node
+    const nvm = deps.join(deps.home, '.nvm', 'versions', 'node');
+    for (const entry of deps.list(nvm)) {
+        const path = deps.join(nvm, entry, 'bin', 'node');
+        if (deps.exists(path))
+            found.push(path);
+    }
+    return [...new Set(found)];
+}
+/**
+ * 돌릴 수 있는가, 못 돌린다면 무엇이 있는가.
+ *
+ * 하한을 넘으면 **아무것도 하지 않는다** — 정상 경로에 I/O를 얹지 않는다. 못 넘을 때만
+ * 후보를 찾고, 후보에 대해서만 `-v` 를 묻는다.
+ */
+export async function checkNodeRuntime(deps) {
+    const major = majorOf(deps.version);
+    if (major !== null && major >= MINIMUM_NODE_MAJOR)
+        return { ok: true, version: deps.version };
+    const candidates = [];
+    for (const path of candidatePaths(deps)) {
+        const probed = await deps.run(path, ['-v']);
+        if (!probed.ok)
+            continue;
+        const version = probed.stdout.trim().split(/\r?\n/)[0] ?? '';
+        const found = majorOf(version);
+        if (found !== null && found >= MINIMUM_NODE_MAJOR)
+            candidates.push({ path, version });
+    }
+    return {
+        ok: false,
+        code: 'NODE_RUNTIME_REQUIRED',
+        version: deps.version,
+        detail: `ASC ${RELEASE_VERSION} needs Node ${MINIMUM_NODE_MAJOR} or newer; this process is ${deps.version}.` +
+            (candidates.length > 0
+                ? ' A newer Node is already on this machine — use it for the same command.'
+                : ' No newer Node was found in the usual places. Installing one is yours to do.'),
+        candidates,
+    };
+}

package/dist/core/distribution/release.d.ts

@@ -1,9 +1,9 @@
 export declare const RUNTIME_PACKAGE = "@asc-agent/runtime";
 export declare const BOOTSTRAP_PACKAGE = "@asc-agent/bootstrap";
 /** runtime과 bootstrap은 초기 release에서 lockstep이다. */
-export declare const RELEASE_VERSION = "0.2.0";
-export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.2.0";
-export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.2.0";
+export declare const RELEASE_VERSION = "0.2.1";
+export declare const RUNTIME_SPEC = "@asc-agent/runtime@0.2.1";
+export declare const BOOTSTRAP_SPEC = "@asc-agent/bootstrap@0.2.1";
 /**
  * 아직 설치되지 않은 machine에서 그대로 실행되는 형태 (C-14 §3.4).
  *

package/dist/core/distribution/release.js

@@ -9,7 +9,7 @@
 export const RUNTIME_PACKAGE = '@asc-agent/runtime';
 export const BOOTSTRAP_PACKAGE = '@asc-agent/bootstrap';
 /** runtime과 bootstrap은 초기 release에서 lockstep이다. */
-export const RELEASE_VERSION = '0.2.0';
+export const RELEASE_VERSION = '0.2.1';
 export const RUNTIME_SPEC = `${RUNTIME_PACKAGE}@${RELEASE_VERSION}`;
 export const BOOTSTRAP_SPEC = `${BOOTSTRAP_PACKAGE}@${RELEASE_VERSION}`;
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asc-agent/runtime",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "ASC (Agent Session Control) — local-first human-in-the-loop agent control plane: core, CLI, and adapters",
   "keywords": [
     "agent",