@n2world/orchestrator 1.1.0

package/dist/beta-runner.js

@@ -0,0 +1,251 @@
+"use strict";
+// ============================================================================
+// 클로즈드 베타 실행 하니스 (B0/B1 운영 — 접지 단계)
+// ----------------------------------------------------------------------------
+// 무한 회귀를 끊는 접지점은 **실사용자**다(master §2). 이 하니스는 실사용자 N명을 온보딩하고,
+// 실 LLM 파이프라인으로 과제를 돌리고, 그들의 라벨(정오·만족)을 수집해 B1 MultiAxisLift 를
+// **실데이터로** 산출한다. 재사용: B0 beta.ts(동의·온보딩·피드백·TierGuard) + personalization +
+// multi-axis-lift + 실 LLM(llm.ts) + LocalSandbox.
+//
+// 제1계명(절대): **에이전트는 자기 채점지를 만들 수 없다.** 성공(정오)·만족 라벨은 **인간 참가자**가
+//   준다. 합성/자체 생성 라벨은 베타 데이터가 아니다. 실 라벨이 모이기 전 리프트는 `(목표; 미측정)`.
+// 헌법 제4조: 모든 베타 데이터는 **로컬에만** 머문다(외부 전송은 ConsentGate+TierGuard 통과 필요).
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BetaSession = void 0;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const beta_1 = require("./beta");
+const personalization_1 = require("./personalization");
+const multi_axis_lift_1 = require("./multi-axis-lift");
+const llm_1 = require("./llm");
+function emptyRuntime() {
+    return { tasks: 0, oracleCalls: 0, totalTimeMs: 0, safetyChecked: 0, safetyBlocked: 0 };
+}
+/**
+ * 한 클로즈드 베타 운영 세션. 참가자별 온보딩→과제→피드백을 누적하고 B1 리프트를 산출한다.
+ * runShell 은 실 샌드박스 실행기(주입). 미주입 시 과제는 도구 없이 LLM 응답만 받는다.
+ */
+class BetaSession {
+    consent = new beta_1.ConsentGate();
+    onboarding = new beta_1.OnboardingTracker();
+    feedback = new beta_1.FeedbackStore();
+    tierGuard = new beta_1.TierGuard();
+    profiles = new Map();
+    runtime = { on: emptyRuntime(), off: emptyRuntime() };
+    taskLog = [];
+    /** 참가자 온보딩 — 동의 범위 부여 + signup 기록(실 타임스탬프). */
+    onboard(userId, scopes = ['feedback-collection', 'telemetry-local'], at = Date.now()) {
+        for (const s of scopes)
+            this.consent.grant(userId, s, at);
+        this.onboarding.record(userId, 'signup', at);
+        if (!this.profiles.has(userId))
+            this.profiles.set(userId, new personalization_1.UserProfile(userId));
+    }
+    profile(userId) {
+        let p = this.profiles.get(userId);
+        if (!p) {
+            p = new personalization_1.UserProfile(userId);
+            this.profiles.set(userId, p);
+        }
+        return p;
+    }
+    /**
+     * 실 LLM 파이프라인으로 과제를 실행한다. arm='on' 이면 누적 사용자 컨텍스트를 주입(얕은 개인화),
+     * 'off' 면 주입하지 않는다(A/B 비교군). 효율(①호출·시간)을 실측 누적한다.
+     */
+    async runTask(userId, taskId, taskText, arm, runShell) {
+        this.onboarding.record(userId, 'first_run');
+        const prof = this.profile(userId);
+        const ctx = arm === 'on' ? prof.contextString() : '';
+        const prompt = ctx ? `사용자 맥락(개인화): ${ctx}\n\n과제: ${taskText}` : taskText;
+        let oracleCalls = 0;
+        const shell = runShell ?? (async () => '[샌드박스 미주입 — 도구 실행 없음]');
+        const t0 = Date.now();
+        let output;
+        try {
+            // 실 LLM 호출(askAgent). 도구 호출마다 oracleCalls 증가(효율 측정).
+            output = await (0, llm_1.askAgent)(prompt, async (cmd) => {
+                oracleCalls++;
+                return shell(cmd);
+            });
+            oracleCalls++; // 최소 1회 LLM 호출
+        }
+        catch (e) {
+            output = `[과제 실행 오류] ${e?.message ?? e}`;
+        }
+        const timeMs = Date.now() - t0;
+        // 사용자 맥락 누적(다음 과제의 개인화에 반영) — 로컬에만.
+        prof.observe(taskText);
+        const rt = this.runtime[arm];
+        rt.tasks++;
+        rt.oracleCalls += oracleCalls;
+        rt.totalTimeMs += timeMs;
+        this.taskLog.push({ userId, taskId, arm, taskText, output, t: Date.now() });
+        return { userId, taskId, arm, output, oracleCalls, timeMs, personalizationContext: ctx };
+    }
+    /**
+     * 참가자(인간)의 라벨을 기록한다. satisfaction1to5 는 1..5 별점(0..1로 정규화), correct 는 정오 판정.
+     * **이 라벨은 인간이 준다 — 자체 생성 금지(제1계명).**
+     */
+    recordFeedback(userId, taskId, satisfaction1to5, correct, arm, note) {
+        const sat = Math.max(0, Math.min(1, (satisfaction1to5 - 1) / 4)); // 1→0, 5→1
+        this.feedback.add({ userId, taskId, satisfaction: sat, correct, arm, note });
+        this.onboarding.record(userId, 'first_feedback');
+    }
+    /** 안전 점검 결과를 arm 에 누적(③ 안전 퇴행 — commit-gate/거버넌스 연동 지점). */
+    recordSafetyCheck(arm, blocked) {
+        const rt = this.runtime[arm];
+        rt.safetyChecked++;
+        if (blocked)
+            rt.safetyBlocked++;
+    }
+    onboardedCount() {
+        return this.onboarding.onboardedCount();
+    }
+    /** arm 별 ArmMetrics 구성 — 피드백(정오·만족) + 런타임(효율·안전)에서. */
+    armMetrics(arm) {
+        const labels = this.feedback.all().filter((l) => l.arm === arm);
+        const answered = labels.filter((l) => l.correct !== null);
+        const heldOutSuccesses = answered.filter((l) => l.correct === true).length;
+        const rt = this.runtime[arm];
+        return {
+            heldOutSuccesses,
+            heldOutTotal: answered.length,
+            oracleCalls: rt.oracleCalls,
+            totalTimeMs: rt.totalTimeMs,
+            redTeamBlocked: rt.safetyBlocked,
+            redTeamTotal: rt.safetyChecked,
+            badHabitReinforced: 0,
+            badHabitOpportunities: 0,
+            meanSatisfaction: this.feedback.meanSatisfaction(arm),
+        };
+    }
+    /**
+     * B1 MultiAxisLift 보고. **실 라벨이 없으면 정직하게 미측정**을 반환한다(자기 채점 금지).
+     * 두 arm 모두에 응답된 정오 라벨이 있어야 의미 있는 리프트가 산출된다.
+     */
+    liftReport() {
+        const on = this.armMetrics('on');
+        const off = this.armMetrics('off');
+        if (on.heldOutTotal === 0 || off.heldOutTotal === 0) {
+            return {
+                status: '(목표; 미측정)',
+                reason: '실사용자 정오 라벨이 두 arm(on/off) 모두에 필요하다. 베타 참가자가 과제를 수행·라벨링하기 전까지 리프트는 미측정이다(접지 영가설 — 바닥은 인간).',
+                onboarded: this.onboardedCount(),
+            };
+        }
+        return { status: 'measured', report: (0, multi_axis_lift_1.computeMultiAxisLift)(on, off), onboarded: this.onboardedCount() };
+    }
+    /** 이미 라벨된 (task,arm) 인가(중복 라벨 안내 회피용). */
+    isLabeled(taskId, arm) {
+        return this.feedback.all().some((l) => l.taskId === taskId && l.arm === arm);
+    }
+    /**
+     * 참가자 라벨링 워크시트(Markdown). 에이전트 출력과 **빈 라벨 칸** + 정확한 feedback 명령을 만든다.
+     * ★ 라벨(정오·만족)은 **실참가자가 직접 채운다** — 운영자/에이전트가 대신 채우지 않는다(제1계명).
+     */
+    worksheet(userId) {
+        const logs = this.taskLog.filter((l) => l.userId === userId).sort((a, b) => a.t - b.t);
+        const lines = [];
+        lines.push(`# 베타 라벨링 워크시트 — 참가자: ${userId}`);
+        lines.push('');
+        lines.push('> ⚠ 아래 각 과제의 에이전트 출력을 보고 **당신(참가자)이 직접** 정오(맞음/틀림)와');
+        lines.push('> 만족도(1~5)를 판단해 표시하세요. 운영자/AI 가 대신 채우면 안 됩니다(접지 원칙).');
+        lines.push('> 표시 후, 각 항목의 명령을 실행해 라벨을 기록하세요.');
+        lines.push('');
+        for (const l of logs) {
+            const labeled = this.isLabeled(l.taskId, l.arm) ? ' ✅(라벨됨)' : '';
+            lines.push(`## ${l.taskId} (arm=${l.arm})${labeled}`);
+            lines.push(`- **과제:** ${l.taskText}`);
+            lines.push(`- **에이전트 출력:**`);
+            lines.push('  > ' + l.output.replace(/\n/g, '\n  > '));
+            lines.push(`- **정오 판단:** [ ] 맞음(y)  [ ] 틀림(n)`);
+            lines.push(`- **만족도(1~5):** [ ]`);
+            lines.push('- **라벨 기록 명령(값 채워서 실행):**');
+            lines.push(`  \`\`\``);
+            lines.push(`  node packages/orchestrator/dist/cli.js beta feedback ${userId} ${l.taskId} 만족1-5 정오y_or_n --arm ${l.arm}`);
+            lines.push(`  \`\`\``);
+            lines.push('');
+        }
+        if (logs.length === 0)
+            lines.push('(이 참가자의 실행된 과제가 없습니다. 먼저 `beta run` 을 수행하세요.)');
+        return lines.join('\n');
+    }
+    taskLogFor(userId) {
+        return this.taskLog.filter((l) => l.userId === userId);
+    }
+    /** 로컬 영속(헌법 제4조 — 외부 전송 아님). 디렉터리 자동 생성. */
+    save(filePath) {
+        const state = {
+            consent: this.consent.records_(),
+            onboarding: this.onboarding.all(),
+            feedback: this.feedback.all(),
+            egress: this.tierGuard.log(),
+            armRuntime: this.runtime,
+            taskLog: this.taskLog,
+        };
+        fs.mkdirSync(path.dirname(path.resolve(filePath)), { recursive: true });
+        fs.writeFileSync(filePath, JSON.stringify(state, null, 2), 'utf8');
+    }
+    /** 로컬 스냅샷에서 세션 복원(이어서 운영). */
+    static load(filePath) {
+        const s = new BetaSession();
+        let state = null;
+        try {
+            state = JSON.parse(fs.readFileSync(filePath, 'utf8'));
+        }
+        catch {
+            return s;
+        }
+        for (const c of state.consent) {
+            if (c.granted)
+                s.consent.grant(c.userId, c.scope, c.t);
+            else
+                s.consent.revoke(c.userId, c.scope, c.t);
+        }
+        for (const o of state.onboarding)
+            s.onboarding.record(o.userId, o.event, o.t);
+        for (const f of state.feedback)
+            s.feedback.add({ userId: f.userId, taskId: f.taskId, satisfaction: f.satisfaction, correct: f.correct, arm: f.arm, note: f.note, t: f.t });
+        if (state.armRuntime)
+            s.runtime = { on: { ...emptyRuntime(), ...state.armRuntime.on }, off: { ...emptyRuntime(), ...state.armRuntime.off } };
+        if (Array.isArray(state.taskLog))
+            s.taskLog = state.taskLog;
+        return s;
+    }
+}
+exports.BetaSession = BetaSession;

package/dist/beta.d.ts

@@ -0,0 +1,102 @@
+export type DataTier = 0 | 1 | 2;
+export type Destination = 'local' | 'external';
+export type ConsentScope = 'llm-transmission' | 'stt' | 'telemetry-local' | 'feedback-collection';
+export interface ConsentRecord {
+    userId: string;
+    scope: ConsentScope;
+    granted: boolean;
+    t: number;
+}
+export declare class ConsentGate {
+    private records;
+    private key;
+    /** 명시적 동의 기록(동의 시점 저장). */
+    grant(userId: string, scope: ConsentScope, at?: number): void;
+    /** 동의 철회 — 헌법 제4조: 사용자는 언제든 철회할 수 있다. */
+    revoke(userId: string, scope: ConsentScope, at?: number): void;
+    hasConsent(userId: string, scope: ConsentScope): boolean;
+    /**
+     * 동의 필요 행동의 게이트. 동의 없으면 차단(allowed=false).
+     * 되돌릴 수 없는/외부 영향 행동 전에 호출한다(영향 프리뷰의 진입점).
+     */
+    requireConsent(userId: string, scope: ConsentScope): {
+        allowed: boolean;
+        reason: string;
+    };
+    records_(): ConsentRecord[];
+}
+export interface EgressAttempt {
+    tier: DataTier;
+    dest: Destination;
+    blocked: boolean;
+    reason: string;
+    t: number;
+}
+export declare class TierGuard {
+    private attempts;
+    /**
+     * 데이터 전송 게이트. Tier-0 의 external 전송은 무조건 차단(`관측 0/N`).
+     * 로컬 전송은 모든 Tier 허용. Tier 1/2 external 은 동의 전제(호출측에서 ConsentGate 확인).
+     */
+    guardEgress(tier: DataTier, dest: Destination): {
+        allowed: boolean;
+        reason: string;
+    };
+    /** `관측 0/N` 보고용 — tier0ExfilObserved 는 항상 0 이어야 안전 충족. */
+    stats(): {
+        externalAttempts: number;
+        tier0ExternalAttempts: number;
+        tier0ExfilObserved: number;
+    };
+    log(): EgressAttempt[];
+}
+export type OnboardingEvent = 'signup' | 'first_run' | 'first_feedback';
+export interface OnboardingRecord {
+    userId: string;
+    event: OnboardingEvent;
+    t: number;
+}
+export declare class OnboardingTracker {
+    private records;
+    /** 실제 이벤트 발생 시각을 기록. at 미지정 시 현재 시각(실측). */
+    record(userId: string, event: OnboardingEvent, at?: number): void;
+    private firstOf;
+    /** signup → first_run 까지 실제 소요(초). 둘 다 있어야 측정값, 아니면 null(미측정). */
+    timeToFirstTaskSec(userId: string): number | null;
+    /** signup 이벤트가 있는 고유 사용자 수(= 온보딩된 N). */
+    onboardedCount(): number;
+    eventsFor(userId: string): OnboardingRecord[];
+    all(): OnboardingRecord[];
+}
+export interface FeedbackLabel {
+    userId: string;
+    taskId: string;
+    /** 만족도∈[0,1] (예: 별점 1..5 → 0..1로 정규화해 저장). */
+    satisfaction: number;
+    /** 사용자가 결과를 정답으로 판단했는가. 미응답이면 null. */
+    correct: boolean | null;
+    /** 개인화 ON/OFF (A/B 귀속 — B1 에서 분리 집계). */
+    arm?: 'on' | 'off';
+    note?: string;
+    t: number;
+}
+export declare class FeedbackStore {
+    private labels;
+    add(label: Omit<FeedbackLabel, 't'> & {
+        t?: number;
+    }): void;
+    all(): FeedbackLabel[];
+    forTask(taskId: string): FeedbackLabel[];
+    /** 평균 만족도(arm 필터 가능). 라벨 없으면 null(미측정 — 정직). */
+    meanSatisfaction(arm?: 'on' | 'off'): number | null;
+    count(): number;
+}
+export interface BetaSnapshot {
+    consent: ConsentRecord[];
+    onboarding: OnboardingRecord[];
+    feedback: FeedbackLabel[];
+    egress: EgressAttempt[];
+}
+/** 베타 상태를 로컬 파일에 저장(외부 반출 아님). 디렉터리는 자동 생성. */
+export declare function saveBetaSnapshot(filePath: string, snap: BetaSnapshot): void;
+export declare function loadBetaSnapshot(filePath: string): BetaSnapshot | null;

package/dist/beta.js

@@ -0,0 +1,180 @@
+"use strict";
+// ============================================================================
+// B0 클로즈드 베타 인프라 — 동의 게이트 · 온보딩 추적 · 피드백 파이프라인 · Tier 가드
+// ----------------------------------------------------------------------------
+// v2.4 §2 GroundingFirst: 무한 회귀를 끊는 접지점은 실사용자다. 이 모듈은 실사용자 N명을
+// 온보딩하고, 그들의 라벨을 접지 스택 3층(모델-비평 캘리브레이션)·B1 4축(④ 만족)의 입력으로
+// 저장한다. 모든 텔레메트리는 실데이터(타임스탬프)이며 Math.random 가짜를 쓰지 않는다(제1계명).
+//
+// 데이터는 로컬에만 머문다(헌법 제4조 — 로컬 기억 보호). 외부 전송은 ConsentGate + TierGuard 통과 필요.
+// ============================================================================
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FeedbackStore = exports.OnboardingTracker = exports.TierGuard = exports.ConsentGate = void 0;
+exports.saveBetaSnapshot = saveBetaSnapshot;
+exports.loadBetaSnapshot = loadBetaSnapshot;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+// ---------------------------------------------------------------------------
+// ConsentGate — 헌법 제4조(영향 프리뷰·로컬 기억 보호) + PRIVACY 동의 게이트
+// ---------------------------------------------------------------------------
+class ConsentGate {
+    records = new Map();
+    key(userId, scope) {
+        return `${userId}::${scope}`;
+    }
+    /** 명시적 동의 기록(동의 시점 저장). */
+    grant(userId, scope, at = Date.now()) {
+        this.records.set(this.key(userId, scope), { userId, scope, granted: true, t: at });
+    }
+    /** 동의 철회 — 헌법 제4조: 사용자는 언제든 철회할 수 있다. */
+    revoke(userId, scope, at = Date.now()) {
+        this.records.set(this.key(userId, scope), { userId, scope, granted: false, t: at });
+    }
+    hasConsent(userId, scope) {
+        return this.records.get(this.key(userId, scope))?.granted === true;
+    }
+    /**
+     * 동의 필요 행동의 게이트. 동의 없으면 차단(allowed=false).
+     * 되돌릴 수 없는/외부 영향 행동 전에 호출한다(영향 프리뷰의 진입점).
+     */
+    requireConsent(userId, scope) {
+        if (this.hasConsent(userId, scope))
+            return { allowed: true, reason: 'consent granted' };
+        return { allowed: false, reason: `동의 필요: ${scope} (사용자 ${userId} 미동의 — 차단)` };
+    }
+    records_() {
+        return [...this.records.values()];
+    }
+}
+exports.ConsentGate = ConsentGate;
+class TierGuard {
+    attempts = [];
+    /**
+     * 데이터 전송 게이트. Tier-0 의 external 전송은 무조건 차단(`관측 0/N`).
+     * 로컬 전송은 모든 Tier 허용. Tier 1/2 external 은 동의 전제(호출측에서 ConsentGate 확인).
+     */
+    guardEgress(tier, dest) {
+        const blocked = tier === 0 && dest === 'external';
+        const reason = blocked
+            ? 'Tier-0 외부 반출 차단 (관측 0/N 보장)'
+            : 'allowed';
+        this.attempts.push({ tier, dest, blocked, reason, t: Date.now() });
+        return { allowed: !blocked, reason };
+    }
+    /** `관측 0/N` 보고용 — tier0ExfilObserved 는 항상 0 이어야 안전 충족. */
+    stats() {
+        const ext = this.attempts.filter((a) => a.dest === 'external');
+        const t0 = ext.filter((a) => a.tier === 0);
+        return {
+            externalAttempts: ext.length,
+            tier0ExternalAttempts: t0.length,
+            tier0ExfilObserved: t0.filter((a) => !a.blocked).length, // 실제로 나간 것(0 이어야 함)
+        };
+    }
+    log() {
+        return this.attempts;
+    }
+}
+exports.TierGuard = TierGuard;
+class OnboardingTracker {
+    records = [];
+    /** 실제 이벤트 발생 시각을 기록. at 미지정 시 현재 시각(실측). */
+    record(userId, event, at = Date.now()) {
+        this.records.push({ userId, event, t: at });
+    }
+    firstOf(userId, event) {
+        const xs = this.records
+            .filter((r) => r.userId === userId && r.event === event)
+            .sort((a, b) => a.t - b.t);
+        return xs.length ? xs[0].t : null;
+    }
+    /** signup → first_run 까지 실제 소요(초). 둘 다 있어야 측정값, 아니면 null(미측정). */
+    timeToFirstTaskSec(userId) {
+        const su = this.firstOf(userId, 'signup');
+        const fr = this.firstOf(userId, 'first_run');
+        if (su === null || fr === null)
+            return null;
+        return +((fr - su) / 1000).toFixed(1);
+    }
+    /** signup 이벤트가 있는 고유 사용자 수(= 온보딩된 N). */
+    onboardedCount() {
+        return new Set(this.records.filter((r) => r.event === 'signup').map((r) => r.userId)).size;
+    }
+    eventsFor(userId) {
+        return this.records.filter((r) => r.userId === userId).sort((a, b) => a.t - b.t);
+    }
+    all() {
+        return this.records;
+    }
+}
+exports.OnboardingTracker = OnboardingTracker;
+class FeedbackStore {
+    labels = [];
+    add(label) {
+        const sat = Math.max(0, Math.min(1, label.satisfaction));
+        this.labels.push({ ...label, satisfaction: sat, t: label.t ?? Date.now() });
+    }
+    all() {
+        return this.labels;
+    }
+    forTask(taskId) {
+        return this.labels.filter((l) => l.taskId === taskId);
+    }
+    /** 평균 만족도(arm 필터 가능). 라벨 없으면 null(미측정 — 정직). */
+    meanSatisfaction(arm) {
+        const xs = (arm ? this.labels.filter((l) => l.arm === arm) : this.labels).map((l) => l.satisfaction);
+        if (xs.length === 0)
+            return null;
+        return +(xs.reduce((a, b) => a + b, 0) / xs.length).toFixed(3);
+    }
+    count() {
+        return this.labels.length;
+    }
+}
+exports.FeedbackStore = FeedbackStore;
+/** 베타 상태를 로컬 파일에 저장(외부 반출 아님). 디렉터리는 자동 생성. */
+function saveBetaSnapshot(filePath, snap) {
+    fs.mkdirSync(path.dirname(path.resolve(filePath)), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(snap, null, 2), 'utf8');
+}
+function loadBetaSnapshot(filePath) {
+    try {
+        return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/browser-agent.d.ts

@@ -0,0 +1,90 @@
+export type BrowserVerb = 'goto' | 'read' | 'click' | 'type' | 'extract' | 'back' | 'vclick';
+export interface BrowserAction {
+    verb: BrowserVerb;
+    url?: string;
+    ref?: string;
+    text?: string;
+    query?: string;
+}
+/** 지각 단위 — 상호작용 가능한 요소(의미 DOM). */
+export interface InteractiveElement {
+    ref: string;
+    role: string;
+    name: string;
+}
+/** 요소 목록을 LLM 친화 라인으로 압축(토큰 효율). 테스트용 export. */
+export declare function formatElements(els: InteractiveElement[], max?: number): string;
+export interface ScreenResult {
+    allowed: boolean;
+    reason: string;
+}
+/**
+ * 브라우저 액션 보안 스크린(deny-by-default for 위험).
+ * read/back/extract 는 허용, goto 는 http(s)만, click 은 금융/인증/되돌릴수없는 라벨이면 차단,
+ * type 은 비밀/결제 필드면 차단(자격증명 입력 금지).
+ */
+export declare function screenBrowserAction(action: BrowserAction, targetName?: string): ScreenResult;
+/** 스크린샷 결과(비전 폴백용). */
+export interface Screenshot {
+    base64: string;
+    width: number;
+    height: number;
+}
+/**
+ * 비전 그라운딩 로케이터(#2 폴백). 스크린샷+설명 → 정규화 좌표(0~1) 또는 null.
+ * llm.ts 의 멀티모달 모델로 구현(주입). 비용이 크므로 DOM(#3)로 안 될 때만 쓴다.
+ */
+export type VisionLocator = (screenshotBase64: string, description: string) => Promise<{
+    x: number;
+    y: number;
+} | null>;
+/** 구동 계층 추상화(테스트에서 모의 가능). */
+export interface IBrowserController {
+    goto(url: string): Promise<void>;
+    /** 현재 페이지의 상호작용 요소를 추출하고 ref 를 부여(의미 DOM #3). */
+    readElements(): Promise<InteractiveElement[]>;
+    click(ref: string): Promise<void>;
+    type(ref: string, text: string): Promise<void>;
+    extractText(): Promise<string>;
+    back(): Promise<void>;
+    close(): Promise<void>;
+    /** 비전 폴백용 스크린샷. */
+    screenshot(): Promise<Screenshot>;
+    /** 비전 폴백용 좌표 클릭(픽셀). */
+    clickAt(x: number, y: number): Promise<void>;
+}
+/**
+ * Playwright 기반 로컬 컨트롤러(#1 구동). Playwright 는 동적 import(선택 설치).
+ * 미설치 시 init() 이 명확히 throw → 상위에서 정직한 안내로 변환.
+ */
+export declare class PlaywrightBrowserController implements IBrowserController {
+    private headless;
+    private browser;
+    private page;
+    constructor(headless?: boolean);
+    init(): Promise<void>;
+    goto(url: string): Promise<void>;
+    readElements(): Promise<InteractiveElement[]>;
+    click(ref: string): Promise<void>;
+    type(ref: string, text: string): Promise<void>;
+    extractText(): Promise<string>;
+    back(): Promise<void>;
+    screenshot(): Promise<Screenshot>;
+    clickAt(x: number, y: number): Promise<void>;
+    close(): Promise<void>;
+}
+/**
+ * BrowserAgent — 지각(read)+구동(click/type/goto)을 보안 스크린으로 감싼 실행기.
+ * act() 가 LLM 도구(controlBrowser)의 백엔드가 된다. 모든 액션은 screenBrowserAction 통과.
+ */
+export declare class BrowserAgent {
+    private ctrl;
+    private vision?;
+    private lastElements;
+    /** 비전 폴백 로케이터(선택). 없으면 vclick 은 안내만. */
+    constructor(ctrl: IBrowserController, vision?: VisionLocator | undefined);
+    /** 한 액션 실행 → 사람이 읽는/LLM이 읽는 결과 문자열. */
+    act(action: BrowserAction): Promise<string>;
+    private refreshAndFormat;
+    close(): Promise<void>;
+}