@asc-agent/runtime 0.3.2 → 0.5.0

package/dist/adapters/markdown/state-store.js

@@ -314,7 +314,8 @@ function renderControlState(state) {
         '# Execution',
         `활성 Block: ${state.activeBlock ?? '없음'}`,
         `활성 세션: ${state.activeSessions.join(', ') || '없음'}`,
-        `Write Boundary 점유: ${state.writeBoundaryOccupancy.join(', ') || '없음'}`,
+        // 객체를 그대로 문자열에 넣으면 "[object Object]" 가 남는다 — 실제 state.md 에서 그렇게 보였다.
+        `Write Boundary 점유: ${state.writeBoundaryOccupancy.map((o) => `${o.sessionId} → ${o.paths.join(' ')}`).join(', ') || '없음'}`,
         `승인 대기: ${state.awaitingController.join(', ') || '없음'}`,
         '',
         '# Monitoring',

package/dist/adapters/service/launchd.d.ts

@@ -0,0 +1,12 @@
+import { type PersistentRuntimeAdapter, type ServiceCommand } from '../../core/distribution/persistent-runtime.ts';
+export declare const plistPath: (home?: string) => string;
+/**
+ * plist 본문. **내용이 곧 비교 기준이다** — 같으면 CURRENT, 다르면 STALE 이다.
+ * digest 를 따로 두지 않는 이유: 파일이 우리가 만들 내용과 같은지 보는 것이 더 정확하다.
+ */
+export declare function launchAgentPlist(command: ServiceCommand): string;
+export type LaunchdDeps = {
+    home?: string;
+    exec?: (command: string, args: readonly string[]) => Promise<void>;
+};
+export declare function launchdAdapter(deps?: LaunchdDeps): PersistentRuntimeAdapter;

package/dist/adapters/service/launchd.js

@@ -0,0 +1,97 @@
+// macOS — user LaunchAgent (설계 §4.3).
+//
+// root daemon 이 아니라 **사용자 것**이다. `~/Library/LaunchAgents/` 에 살고 로그인 이후에
+// 돈다. 그것이 이 계약의 경계이고, 그 위로 올리지 않는다 — 사람의 세션과 무관하게 도는
+// 것은 사용자가 켜지 않은 상시 프로세스이며 다른 종류의 결정이다.
+//
+// `StartInterval` 로 짧은 회차를 반복시킨다. 계속 도는 프로세스를 등록하지 않는 이유는
+// port 주석에 있다: 죽었을 때 되살리는 일을 OS 가 더 잘한다.
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { promisify } from 'node:util';
+import { SERVICE_LABEL, } from "../../core/distribution/persistent-runtime.js";
+const run = promisify(execFile);
+export const plistPath = (home = homedir()) => join(home, 'Library', 'LaunchAgents', `${SERVICE_LABEL}.plist`);
+/** XML 이스케이프. 경로에 `&` 가 있는 기계가 실제로 있다. */
+const xml = (value) => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+/**
+ * plist 본문. **내용이 곧 비교 기준이다** — 같으면 CURRENT, 다르면 STALE 이다.
+ * digest 를 따로 두지 않는 이유: 파일이 우리가 만들 내용과 같은지 보는 것이 더 정확하다.
+ */
+export function launchAgentPlist(command) {
+    const args = [command.program, ...command.args].map((arg) => `    <string>${xml(arg)}</string>`).join('\n');
+    // 키를 정렬해 적는다 — 같은 환경이면 같은 문서여야 CURRENT 판정이 선다.
+    const env = Object.entries(command.environment ?? {}).sort(([a], [b]) => a.localeCompare(b));
+    const environment = env.length === 0
+        ? ''
+        : `  <key>EnvironmentVariables</key>
+  <dict>
+${env.map(([key, value]) => `    <key>${xml(key)}</key>\n    <string>${xml(value)}</string>`).join('\n')}
+  </dict>
+`;
+    // 회차가 무엇을 했는지 볼 자리. 없으면 launchd 는 출력을 버리고, 실패는 종료 코드 하나로만 남는다.
+    const logs = command.logPath
+        ? `  <key>StandardOutPath</key>
+  <string>${xml(command.logPath)}</string>
+  <key>StandardErrorPath</key>
+  <string>${xml(command.logPath)}</string>
+`
+        : '';
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${SERVICE_LABEL}</string>
+  <key>ProgramArguments</key>
+  <array>
+${args}
+  </array>
+${environment}${logs}  <key>StartInterval</key>
+  <integer>${command.intervalSeconds}</integer>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>ProcessType</key>
+  <string>Background</string>
+</dict>
+</plist>
+`;
+}
+export function launchdAdapter(deps = {}) {
+    const home = deps.home ?? homedir();
+    const path = plistPath(home);
+    const exec = deps.exec ??
+        (async (command, args) => {
+            await run(command, [...args]);
+        });
+    return {
+        id: 'launchd',
+        async supported() {
+            return process.platform === 'darwin';
+        },
+        async status(command) {
+            const wanted = launchAgentPlist(command);
+            const existing = await readFile(path, 'utf8').catch(() => null);
+            if (existing === null)
+                return { kind: 'ABSENT' };
+            if (existing === wanted)
+                return { kind: 'CURRENT', detail: path };
+            // 우리 파일이 우리 내용과 다르다 — 경로나 간격이 바뀌었다는 뜻이다.
+            return { kind: 'STALE', detail: `${path} does not match the current runtime` };
+        },
+        async install(command) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, launchAgentPlist(command), 'utf8');
+            // 다시 읽히게 한다. 이미 없는 것을 unload 하는 것은 오류가 아니므로 삼킨다.
+            await exec('launchctl', ['unload', path]).catch(() => undefined);
+            await exec('launchctl', ['load', path]);
+        },
+        async uninstall() {
+            await exec('launchctl', ['unload', path]).catch(() => undefined);
+            // 우리가 만든 것만 지운다. 없으면 지울 것이 없다.
+            await rm(path, { force: true });
+        },
+    };
+}

package/dist/adapters/service/schtasks.d.ts

@@ -0,0 +1,16 @@
+import { type PersistentRuntimeAdapter, type ServiceCommand } from '../../core/distribution/persistent-runtime.ts';
+/** 작업 이름. `\` 없이 두면 루트 폴더에 만들어진다. */
+export declare const TASK_NAME = "com.asc-agent.runtime";
+/**
+ * `/TR` 에 들어갈 한 줄.
+ *
+ * schtasks 는 명령을 문자열 하나로 받는다 — 경로에 공백이 있으면 통째로 깨지므로
+ * 각 조각을 따옴표로 감싼다. 따옴표가 든 인자는 등록 자체를 깨뜨리므로 거른다.
+ */
+export declare function taskRunLine(command: ServiceCommand): string;
+/** 분 단위 반복. 1분 아래로는 Task Scheduler 가 받지 않는다. */
+export declare const taskMinutes: (intervalSeconds: number) => number;
+export type SchtasksDeps = {
+    exec?: (command: string, args: readonly string[]) => Promise<string>;
+};
+export declare function schtasksAdapter(deps?: SchtasksDeps): PersistentRuntimeAdapter;

package/dist/adapters/service/schtasks.js

@@ -0,0 +1,67 @@
+// Windows — 사용자 Scheduled Task (설계 §4.3).
+//
+// 시스템 서비스가 아니라 **로그인한 사용자의 작업**이다. `/RU` 없이 만들면 현재 사용자로
+// 등록되고, 그것이 이 계약의 경계다.
+//
+// 반복은 Task Scheduler 가 한다(`/SC MINUTE /MO n`). ASC 는 한 회차만 도는 명령을 준다.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { SERVICE_LABEL, } from "../../core/distribution/persistent-runtime.js";
+const run = promisify(execFile);
+/** 작업 이름. `\` 없이 두면 루트 폴더에 만들어진다. */
+export const TASK_NAME = SERVICE_LABEL;
+/**
+ * `/TR` 에 들어갈 한 줄.
+ *
+ * schtasks 는 명령을 문자열 하나로 받는다 — 경로에 공백이 있으면 통째로 깨지므로
+ * 각 조각을 따옴표로 감싼다. 따옴표가 든 인자는 등록 자체를 깨뜨리므로 거른다.
+ */
+export function taskRunLine(command) {
+    const quote = (value) => `\\"${value}\\"`;
+    return [command.program, ...command.args].map(quote).join(' ');
+}
+/** 분 단위 반복. 1분 아래로는 Task Scheduler 가 받지 않는다. */
+export const taskMinutes = (intervalSeconds) => Math.max(1, Math.round(intervalSeconds / 60));
+export function schtasksAdapter(deps = {}) {
+    const exec = deps.exec ??
+        (async (command, args) => {
+            const { stdout } = await run(command, [...args]);
+            return stdout;
+        });
+    return {
+        id: 'schtasks',
+        async supported() {
+            return process.platform === 'win32';
+        },
+        async status(command) {
+            const query = await exec('schtasks', ['/Query', '/TN', TASK_NAME, '/FO', 'LIST', '/V']).catch(() => null);
+            // 조회가 실패하는 것은 대개 "없다"이다. 없는 것과 못 읽은 것을 구분할 방법이
+            // schtasks 에는 없으므로, 없는 쪽으로 읽고 install 이 다시 판정하게 둔다.
+            if (query === null)
+                return { kind: 'ABSENT' };
+            const wanted = taskRunLine(command).replace(/\\"/g, '"');
+            // 조회 출력에 우리 명령이 그대로 들어 있는가. 없으면 낡은 등록이다.
+            return query.includes(wanted)
+                ? { kind: 'CURRENT', detail: TASK_NAME }
+                : { kind: 'STALE', detail: `${TASK_NAME} runs a different command` };
+        },
+        async install(command) {
+            // `/F` 로 덮어쓴다 — 같은 이름의 우리 등록을 지금 형태로 수렴시키는 것이다.
+            await exec('schtasks', [
+                '/Create',
+                '/F',
+                '/TN',
+                TASK_NAME,
+                '/TR',
+                taskRunLine(command),
+                '/SC',
+                'MINUTE',
+                '/MO',
+                String(taskMinutes(command.intervalSeconds)),
+            ]);
+        },
+        async uninstall() {
+            await exec('schtasks', ['/Delete', '/TN', TASK_NAME, '/F']).catch(() => undefined);
+        },
+    };
+}

package/dist/adapters/service/systemd-user.d.ts

@@ -0,0 +1,15 @@
+import { type PersistentRuntimeAdapter, type ServiceCommand } from '../../core/distribution/persistent-runtime.ts';
+export declare const unitDir: (home?: string) => string;
+export declare const SERVICE_UNIT = "com.asc-agent.runtime.service";
+export declare const TIMER_UNIT = "com.asc-agent.runtime.timer";
+export declare function serviceUnit(command: ServiceCommand): string;
+export declare function timerUnit(command: ServiceCommand): string;
+export type SystemdDeps = {
+    home?: string;
+    exec?: (command: string, args: readonly string[]) => Promise<void>;
+    /** systemd --user 를 쓸 수 있는가. 테스트 주입점. */
+    available?: () => Promise<boolean>;
+};
+export declare function systemdUserAdapter(deps?: SystemdDeps): PersistentRuntimeAdapter;
+/** 이 기계에 맞는 adapter. 모르면 `null` — 없는 것을 있는 척하지 않는다. */
+export declare function serviceAdapterFor(platform: NodeJS.Platform): 'launchd' | 'schtasks' | 'systemd-user' | null;

package/dist/adapters/service/systemd-user.js

@@ -0,0 +1,98 @@
+// Linux — systemd --user (설계 §4.3).
+//
+// 사용자 세션에 묶인다. **lingering 을 조용히 켜지 않는다** — 그것은 "로그아웃해도 돈다"는
+// 뜻이고, 사용자가 하지 않은 결정이다. 필요해지면 사람이 명시적으로 켠다.
+//
+// timer 가 주기를 갖고 service 가 한 회차를 돈다. 계속 도는 프로세스를 두지 않는 이유는
+// port 주석과 같다.
+import { execFile } from 'node:child_process';
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { promisify } from 'node:util';
+import { SERVICE_LABEL, } from "../../core/distribution/persistent-runtime.js";
+const run = promisify(execFile);
+export const unitDir = (home = homedir()) => join(home, '.config', 'systemd', 'user');
+export const SERVICE_UNIT = `${SERVICE_LABEL}.service`;
+export const TIMER_UNIT = `${SERVICE_LABEL}.timer`;
+/** systemd 인자 인용. 공백이 든 경로가 통째로 깨지지 않게 한다. */
+const quote = (value) => `"${value.replace(/(["\\])/g, '\\$1')}"`;
+export function serviceUnit(command) {
+    return `[Unit]
+Description=ASC persistent runtime
+
+[Service]
+Type=oneshot
+ExecStart=${[command.program, ...command.args].map(quote).join(' ')}
+${Object.entries(command.environment ?? {})
+        .sort(([a], [b]) => a.localeCompare(b))
+        .map(([key, value]) => `Environment=${quote(`${key}=${value}`)}\n`)
+        .join('')}`;
+}
+export function timerUnit(command) {
+    return `[Unit]
+Description=ASC persistent runtime schedule
+
+[Timer]
+OnBootSec=${command.intervalSeconds}
+OnUnitActiveSec=${command.intervalSeconds}
+Unit=${SERVICE_UNIT}
+
+[Install]
+WantedBy=timers.target
+`;
+}
+export function systemdUserAdapter(deps = {}) {
+    const home = deps.home ?? homedir();
+    const dir = unitDir(home);
+    const exec = deps.exec ??
+        (async (command, args) => {
+            await run(command, [...args]);
+        });
+    const available = deps.available ??
+        (async () => {
+            if (process.platform !== 'linux')
+                return false;
+            // 컨테이너처럼 user bus 가 없는 자리가 흔하다 — 있는 척하지 않는다.
+            return run('systemctl', ['--user', 'show-environment'])
+                .then(() => true)
+                .catch(() => false);
+        });
+    return {
+        id: 'systemd-user',
+        supported: available,
+        async status(command) {
+            const service = await readFile(join(dir, SERVICE_UNIT), 'utf8').catch(() => null);
+            const timer = await readFile(join(dir, TIMER_UNIT), 'utf8').catch(() => null);
+            if (service === null || timer === null)
+                return { kind: 'ABSENT' };
+            return service === serviceUnit(command) && timer === timerUnit(command)
+                ? { kind: 'CURRENT', detail: dir }
+                : { kind: 'STALE', detail: `${dir} does not match the current runtime` };
+        },
+        async install(command) {
+            await mkdir(dir, { recursive: true });
+            await writeFile(join(dir, SERVICE_UNIT), serviceUnit(command), 'utf8');
+            await writeFile(join(dir, TIMER_UNIT), timerUnit(command), 'utf8');
+            await exec('systemctl', ['--user', 'daemon-reload']);
+            await exec('systemctl', ['--user', 'enable', '--now', TIMER_UNIT]);
+        },
+        async uninstall() {
+            await exec('systemctl', ['--user', 'disable', '--now', TIMER_UNIT]).catch(() => undefined);
+            // 우리가 만든 것만 지운다.
+            await rm(join(dir, TIMER_UNIT), { force: true });
+            await rm(join(dir, SERVICE_UNIT), { force: true });
+            await exec('systemctl', ['--user', 'daemon-reload']).catch(() => undefined);
+        },
+    };
+}
+/** 이 기계에 맞는 adapter. 모르면 `null` — 없는 것을 있는 척하지 않는다. */
+export function serviceAdapterFor(platform) {
+    if (platform === 'darwin')
+        return 'launchd';
+    if (platform === 'win32')
+        return 'schtasks';
+    if (platform === 'linux')
+        return 'systemd-user';
+    return null;
+}

package/dist/adapters/webhook/ingress.d.ts

@@ -32,8 +32,8 @@ export declare const IngressRecord: z.ZodObject<{
         raw?: unknown;
         hints?: Record<string, unknown> | undefined;
     };
-    seq: number;
     receivedAt: string;
+    seq: number;
 }, {
     event: {
         detectedAt: string;
@@ -42,8 +42,8 @@ export declare const IngressRecord: z.ZodObject<{
         raw?: unknown;
         hints?: Record<string, unknown> | undefined;
     };
-    seq: number;
     receivedAt: string;
+    seq: number;
 }>;
 export type IngressRecord = z.infer<typeof IngressRecord>;
 export type VerifyOutcome = {