@n2world/orchestrator 1.1.0

package/dist/finance-workflow.js

@@ -0,0 +1,242 @@
+"use strict";
+// ============================================================================
+// BM 출원③ 보강 PoC — 금융 업무 자동화 워크플로우 (경비/송금 품의)
+// ----------------------------------------------------------------------------
+// 특허 청구항 매핑(doc/N2World_특허전략_인프라알고리즘·BM_v1.0.md §4):
+//   [700] 옴니채널 수신   → process()의 입력(channel/requester 세션)
+//   [710] 산업 워크플로우  → FinanceWorkflowEngine (금융 템플릿)
+//   [720] 권한위임 토큰 caveat(규제경계) → Macaroon attenuate + FinanceCaveatVerifier
+//   [730] 독립 검증 오라클 → FinanceOracle (에이전트가 만들지 않은 규정/이중지급/직무분리 검사)
+//   [740] 거버넌스(비용·감사·킬스위치) → AuditLog + killSwitch
+//   [750] 두 갈래 신호(가치 v / 신뢰 t) → A2ATrustGate (t 미달 시 고가치라도 차단)
+//
+// 정직 고지(제1계명):
+//  - 보안 토큰·신뢰는 **실제 구현(agent-os-rd.ts)을 재사용**한다(가짜 게이트 금지).
+//  - 행동 후보 생성기는 **주입형(pluggable)**. PoC 기본값은 결정적 룰 생성기이며,
+//    프로덕션 경로는 출원① 룰기반 MCTS(predictive-agent)다 — 이를 MCTS라고 표기하지 않는다.
+//  - 모든 차단/통과는 테스트로 재현·측정된다(동작 증거).
+// ============================================================================
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FinanceWorkflowEngine = exports.AuditLog = exports.FinanceOracle = exports.FinanceCaveatVerifier = exports.FinanceCaveat = void 0;
+exports.issueFinanceToken = issueFinanceToken;
+const agent_os_rd_1 = require("./agent-os-rd");
+/** 720 — 토큰에 부가된 금융 규제 caveat(문자열 표현). */
+exports.FinanceCaveat = {
+    amountMax: (limit) => `fin.amount <= ${limit}`,
+    approvalRequired: () => `fin.approval = required`,
+    segregationOfDuties: () => `fin.requester != approver`,
+    categoryAllow: (cats) => `fin.category in ${cats.join('|')}`,
+};
+// ---------------------------------------------------------------------------
+// 720 — FinanceCaveatVerifier: 토큰 서명 무결성(실제 Macaroon) + 금융 caveat 강제
+// ---------------------------------------------------------------------------
+class FinanceCaveatVerifier {
+    secret;
+    constructor(secret) {
+        this.secret = secret;
+    }
+    /**
+     * ① 실제 MacaroonVerifier 로 서명체인·기본 caveat(target/expires/path) 검증
+     * ② 금융 caveat(fin.*)을 요청에 대해 강제
+     * 반환: { ok, violations }. 위반 사유는 감사 로그로 남는다.
+     */
+    check(token, req, ctx) {
+        const violations = [];
+        // ① 서명/기본 caveat — 위조·범위밖·만료면 즉시 실패(HARD_GATE).
+        if (!agent_os_rd_1.MacaroonVerifier.verify(token, this.secret, ctx)) {
+            return { ok: false, violations: ['HARD_GATE 실패(서명/target/expires/path)'] };
+        }
+        // ② 금융 caveat 파싱·강제
+        let macaroon;
+        try {
+            macaroon = agent_os_rd_1.Macaroon.deserialize(token);
+        }
+        catch {
+            return { ok: false, violations: ['토큰 파싱 실패'] };
+        }
+        for (const c of macaroon.caveats) {
+            const m1 = c.match(/^fin\.amount <= (\d+(?:\.\d+)?)$/);
+            if (m1) {
+                const limit = parseFloat(m1[1]);
+                if (!(req.amount <= limit))
+                    violations.push(`금액 한도 초과(${req.amount} > ${limit})`);
+                continue;
+            }
+            if (c === 'fin.approval = required') {
+                if (!req.approver)
+                    violations.push('승인자 미지정(승인 필요 caveat)');
+                continue;
+            }
+            if (c === 'fin.requester != approver') {
+                if (req.approver && req.approver === req.requester)
+                    violations.push('직무분리 위반(품의자=승인자)');
+                continue;
+            }
+            const m2 = c.match(/^fin\.category in (.+)$/);
+            if (m2) {
+                const allowed = m2[1].split('|');
+                if (!allowed.includes(req.category))
+                    violations.push(`허용외 계정과목(${req.category})`);
+                continue;
+            }
+        }
+        return { ok: violations.length === 0, violations };
+    }
+}
+exports.FinanceCaveatVerifier = FinanceCaveatVerifier;
+class FinanceOracle {
+    allowedCategories;
+    dedupeKey;
+    ruleset;
+    /** 이중지급 탐지용 원장: (payee|amount|date) → 최초 요청 id. */
+    paidLedger = new Map();
+    constructor(
+    /** 정책상 허용 계정과목(독립 정의 — 에이전트가 수정 못함). 규정셋 미지정 시 사용. */
+    allowedCategories = ['travel', 'meal', 'office', 'vendor', 'payroll'], 
+    /** 이중지급 판정 키. */
+    dedupeKey = (r) => `${r.payee}|${r.amount}|${r.date}`, 
+    /** 관할 규정셋(옵션). 지정 시 계정과목·SoD·승인·한도·고액보고를 규정셋이 결정. */
+    ruleset) {
+        this.allowedCategories = allowedCategories;
+        this.dedupeKey = dedupeKey;
+        this.ruleset = ruleset;
+    }
+    validate(req, generatedAction) {
+        const violations = [];
+        const flags = [];
+        // 0) 자기채점/조작 탐지: 생성된 행동이 검증을 우회하려는 하드코드 패턴인가.
+        const cheat = /skip[_ ]?(audit|oracle|check)|force[_ ]?approve|bypass/i.test(generatedAction);
+        if (cheat) {
+            return { passed: false, violations: ['오라클 우회 시도 탐지'], cheatDetected: true, flags };
+        }
+        // 1) 오라클 고유 검증(규정셋과 무관하게 항상): 금액·수취처
+        if (!(req.amount > 0))
+            violations.push('금액 비정상(≤0)');
+        if (!req.payee)
+            violations.push('수취처 누락');
+        // 2) 이중지급 탐지(오라클 원장 기반) — 동일 (수취처·금액·일자) 반복
+        const key = this.dedupeKey(req);
+        const dup = this.paidLedger.has(key);
+        if (dup)
+            violations.push(`이중지급 의심(기존 요청 ${this.paidLedger.get(key)} 와 동일)`);
+        // 3) 규정 준수 — 규정셋(있으면)이 계정과목·SoD·승인·한도·고액보고를 결정, 없으면 데모 규칙.
+        if (this.ruleset) {
+            const ev = this.ruleset.evaluate(req);
+            violations.push(...ev.blocks);
+            flags.push(...ev.flags);
+            if (dup)
+                flags.push('[KR-STR-001] 이중지급 의심 — 차단 및 보고/추가검토 대상');
+        }
+        else {
+            if (!this.allowedCategories.includes(req.category))
+                violations.push(`규정외 계정과목(${req.category})`);
+            if (req.type === 'transfer' && !req.approver)
+                violations.push('송금은 승인자 필수');
+            if (req.approver && req.approver === req.requester)
+                violations.push('SoD 위반(품의자=승인자)');
+        }
+        const passed = violations.length === 0;
+        if (passed)
+            this.paidLedger.set(key, req.id); // 합격분만 원장 기록(집행됨으로 간주)
+        return { passed, violations, cheatDetected: false, flags };
+    }
+}
+exports.FinanceOracle = FinanceOracle;
+class AuditLog {
+    entries = [];
+    seq = 0;
+    record(e) {
+        const auditId = `aud-${++this.seq}`;
+        this.entries.push({ ...e, auditId, ts: Date.now() });
+        return auditId;
+    }
+    all() { return [...this.entries]; }
+}
+exports.AuditLog = AuditLog;
+const defaultCandidateGenerator = (req) => `${req.type === 'transfer' ? '송금' : '경비'} 품의 승인 및 지급 큐 등록: ${req.payee} ${req.amount}원 (${req.category})`;
+// ---------------------------------------------------------------------------
+// 710 — FinanceWorkflowEngine: 채널 수신 → caveat → 오라클 → 실행 (두 갈래 신호 게이트)
+// ---------------------------------------------------------------------------
+class FinanceWorkflowEngine {
+    verifier;
+    trustGate;
+    oracle;
+    audit;
+    gen;
+    valueRef;
+    killSwitch;
+    governance;
+    constructor(opts) {
+        this.verifier = new FinanceCaveatVerifier(opts.secret);
+        this.trustGate = opts.trustGate;
+        this.oracle = opts.oracle ?? new FinanceOracle();
+        this.audit = opts.audit ?? new AuditLog();
+        this.gen = opts.candidateGenerator ?? defaultCandidateGenerator;
+        this.valueRef = opts.valueRefAmount ?? 1_000_000;
+        this.killSwitch = opts.killSwitch ?? (() => false);
+        this.governance = opts.governance;
+    }
+    auditLog() { return this.audit; }
+    /** 가치 v∈[0,1]: 사업 우선순위(금액 비례, 상한 1). 신뢰 t와 독립 산출. */
+    computeValue(req) {
+        return Math.max(0, Math.min(1, req.amount / this.valueRef));
+    }
+    /**
+     * 금융 품의 1건을 처리한다. 통제 순서: 킬스위치 → 신뢰(t) → caveat(720) → 오라클(730) → 실행.
+     * 각 단계 결과를 controls 에 누적하고 감사 로그에 기록한다.
+     */
+    process(req, token, ctx) {
+        const controls = [];
+        const value = this.computeValue(req);
+        const finalize = (approved, decidedBy, trust, violations) => {
+            const auditId = this.audit.record({ requestId: req.id, decidedBy, approved, trust, value, violations });
+            // 740 거버넌스 영속 결선: 결정을 governance.record()로 흘려 sink(디스크)에 내구 기록.
+            this.governance?.record('finance-decision', JSON.stringify({
+                auditId, requestId: req.id, decidedBy, approved, trust: +trust.toFixed(3), value: +value.toFixed(3), violations,
+            }));
+            return { requestId: req.id, approved, decidedBy, controls, value, trust, violations, auditId };
+        };
+        // 740 킬스위치(로컬 토글 또는 거버넌스 킬스위치 어느 쪽이든 활성이면 중단)
+        if (this.killSwitch() || this.governance?.isKilled()) {
+            controls.push({ control: 'execute', passed: false, reason: '킬스위치 활성 — 자동화 중단' });
+            return finalize(false, 'execute', 0, ['killswitch']);
+        }
+        // 750 신뢰 t — 고가치(value↑)라도 t 미달이면 차단(두 갈래 신호 독립).
+        const t = this.trustGate.evaluate(req.requester, token, ctx);
+        controls.push({ control: 'trust', passed: t.allowed, reason: t.reason });
+        if (!t.allowed)
+            return finalize(false, 'trust', t.trust, [t.reason]);
+        // 720 caveat(규제 경계)
+        const cav = this.verifier.check(token, req, ctx);
+        controls.push({ control: 'caveat', passed: cav.ok, reason: cav.ok ? 'ok' : cav.violations.join('; ') });
+        if (!cav.ok) {
+            this.trustGate.ledgerRef().recordViolation(req.requester); // 위반은 평판 감점
+            return finalize(false, 'caveat', t.trust, cav.violations);
+        }
+        // 행동 후보 생성(주입형) → 730 독립 오라클 검증
+        const action = this.gen(req);
+        const ora = this.oracle.validate(req, action);
+        controls.push({ control: 'oracle', passed: ora.passed, reason: ora.passed ? 'ok' : ora.violations.join('; ') });
+        if (!ora.passed) {
+            if (ora.cheatDetected)
+                this.trustGate.ledgerRef().recordViolation(req.requester);
+            return finalize(false, 'oracle', t.trust, ora.violations);
+        }
+        // 규정 보고 플래그(CTR/STR 등 — 차단 아님)는 거버넌스 감사에 별도 기록(영속).
+        if (ora.flags && ora.flags.length > 0) {
+            this.governance?.record('compliance-flag', JSON.stringify({ requestId: req.id, flags: ora.flags }));
+        }
+        // 실행(시뮬 부킹) + 평판 가점
+        controls.push({ control: 'execute', passed: true, reason: action });
+        this.trustGate.ledgerRef().recordSuccess(req.requester);
+        return finalize(true, 'execute', t.trust, []);
+    }
+}
+exports.FinanceWorkflowEngine = FinanceWorkflowEngine;
+/** 헬퍼: 역할/세션에 금융 caveat 를 부가한 위임 토큰 발급(720). */
+function issueFinanceToken(secret, identifier, target, caveats) {
+    let m = agent_os_rd_1.Macaroon.create(secret, identifier, target);
+    for (const c of caveats)
+        m = agent_os_rd_1.Macaroon.attenuate(m, c);
+    return agent_os_rd_1.Macaroon.serialize(m);
+}

package/dist/gateway.d.ts

@@ -0,0 +1,18 @@
+import { EventEmitter } from 'events';
+export declare class GatewayServer extends EventEmitter {
+    private server;
+    private port;
+    constructor(port: number);
+    /** 실제 바인딩된 포트(port 0 으로 시작했으면 OS 할당 포트). */
+    getPort(): number;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+}
+export declare class GatewayClient {
+    private socket;
+    private port;
+    constructor(port: number);
+    connect(): Promise<void>;
+    sendMessage(type: string, content?: string): void;
+    disconnect(): Promise<void>;
+}

package/dist/gateway.js

@@ -0,0 +1,123 @@
+"use strict";
+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.GatewayClient = exports.GatewayServer = void 0;
+const net = __importStar(require("net"));
+const events_1 = require("events");
+class GatewayServer extends events_1.EventEmitter {
+    server = null;
+    port;
+    constructor(port) {
+        super();
+        this.port = port;
+    }
+    /** 실제 바인딩된 포트(port 0 으로 시작했으면 OS 할당 포트). */
+    getPort() {
+        return this.port;
+    }
+    async start() {
+        return new Promise((resolve, reject) => {
+            this.server = net.createServer((socket) => {
+                let buffer = '';
+                socket.on('data', (data) => {
+                    buffer += data.toString();
+                    let boundary = buffer.indexOf('\n');
+                    while (boundary !== -1) {
+                        const line = buffer.substring(0, boundary).trim();
+                        buffer = buffer.substring(boundary + 1);
+                        if (line.length > 0) {
+                            try {
+                                const message = JSON.parse(line);
+                                this.emit('message', message);
+                            }
+                            catch (err) {
+                                // ignore malformed JSON
+                            }
+                        }
+                        boundary = buffer.indexOf('\n');
+                    }
+                });
+            });
+            const onError = (err) => { this.server.removeListener('error', onError); reject(err); };
+            this.server.once('error', onError); // EADDRINUSE 등 정직히 reject
+            this.server.listen(this.port, '127.0.0.1', () => {
+                this.server.removeListener('error', onError);
+                const addr = this.server.address();
+                if (addr && typeof addr === 'object' && addr.port)
+                    this.port = addr.port; // port 0 → 실제 포트
+                resolve();
+            });
+        });
+    }
+    async stop() {
+        if (this.server) {
+            return new Promise((resolve) => {
+                this.server.close(() => {
+                    resolve();
+                });
+            });
+        }
+    }
+}
+exports.GatewayServer = GatewayServer;
+class GatewayClient {
+    socket = null;
+    port;
+    constructor(port) {
+        this.port = port;
+    }
+    async connect() {
+        return new Promise((resolve, reject) => {
+            this.socket = new net.Socket();
+            this.socket.connect(this.port, '127.0.0.1', () => {
+                resolve();
+            });
+            this.socket.on('error', (err) => {
+                reject(err);
+            });
+        });
+    }
+    sendMessage(type, content) {
+        if (this.socket) {
+            this.socket.write(JSON.stringify({ type, content }) + '\n');
+        }
+    }
+    async disconnect() {
+        if (this.socket) {
+            this.socket.destroy();
+        }
+    }
+}
+exports.GatewayClient = GatewayClient;

package/dist/governance.d.ts

@@ -0,0 +1,39 @@
+import { BudgetGuard } from './value-calibration';
+export interface AuditEvent {
+    t: number;
+    type: string;
+    detail: string;
+}
+/** 감사 영속 sink(옵션). record() 시 동기 호출된다. 미지정이면 인메모리만(기존 동작). */
+export type AuditSink = (e: AuditEvent) => void;
+export declare class GovernanceController {
+    private budget;
+    /** 영속 sink(옵션) — 지정 시 모든 감사 이벤트를 디스크 등으로 내구 기록. */
+    private sink?;
+    private killed;
+    private audit;
+    constructor(budget?: BudgetGuard, 
+    /** 영속 sink(옵션) — 지정 시 모든 감사 이벤트를 디스크 등으로 내구 기록. */
+    sink?: AuditSink | undefined);
+    /** S3 킬스위치: 즉시 모든 행동 차단. */
+    kill(reason?: string): void;
+    reset(): void;
+    isKilled(): boolean;
+    /**
+     * 행동 인가: 킬스위치 OFF ∧ 예산 내일 때만 허용. 모든 결정을 감사 로그에 남긴다.
+     * @param cost 이 행동의 비용(토큰/금액 등 동일 단위).
+     */
+    authorize(action: string, cost?: number): {
+        allowed: boolean;
+        reason: string;
+    };
+    record(type: string, detail: string): void;
+    getAuditLog(): AuditEvent[];
+    budgetRemaining(): number;
+    /** 대시보드/CLI 노출용 상태 스냅샷. */
+    status(): {
+        killed: boolean;
+        budgetRemaining: number;
+        auditCount: number;
+    };
+}

package/dist/governance.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GovernanceController = void 0;
+const value_calibration_1 = require("./value-calibration");
+class GovernanceController {
+    budget;
+    sink;
+    killed = false;
+    audit = [];
+    constructor(budget = new value_calibration_1.BudgetGuard(Number.POSITIVE_INFINITY), 
+    /** 영속 sink(옵션) — 지정 시 모든 감사 이벤트를 디스크 등으로 내구 기록. */
+    sink) {
+        this.budget = budget;
+        this.sink = sink;
+    }
+    /** S3 킬스위치: 즉시 모든 행동 차단. */
+    kill(reason = 'manual') { this.killed = true; this.record('killswitch', reason); }
+    reset() { this.killed = false; this.record('reset', ''); }
+    isKilled() { return this.killed; }
+    /**
+     * 행동 인가: 킬스위치 OFF ∧ 예산 내일 때만 허용. 모든 결정을 감사 로그에 남긴다.
+     * @param cost 이 행동의 비용(토큰/금액 등 동일 단위).
+     */
+    authorize(action, cost = 0) {
+        if (this.killed) {
+            this.record('blocked', `${action} (killswitch)`);
+            return { allowed: false, reason: 'killswitch active' };
+        }
+        if (cost > 0 && !this.budget.trySpend(cost)) {
+            this.record('blocked', `${action} (budget, need=${cost}, left=${this.budget.remaining()})`);
+            return { allowed: false, reason: 'budget exceeded' };
+        }
+        this.record('authorized', `${action} cost=${cost}`);
+        return { allowed: true, reason: 'ok' };
+    }
+    record(type, detail) {
+        const e = { t: Date.now(), type, detail };
+        this.audit.push(e);
+        this.sink?.(e); // 영속 sink(있으면) — 디스크 등 내구 기록
+    }
+    getAuditLog() { return this.audit; }
+    budgetRemaining() { return this.budget.remaining(); }
+    /** 대시보드/CLI 노출용 상태 스냅샷. */
+    status() {
+        return { killed: this.killed, budgetRemaining: this.budget.remaining(), auditCount: this.audit.length };
+    }
+}
+exports.GovernanceController = GovernanceController;

package/dist/governed-executor.d.ts

@@ -0,0 +1,31 @@
+import { GovernanceController } from './governance';
+import { CostApprover, ModelPricing } from './cost-estimator';
+export interface GovernedExecutorOptions {
+    model?: string;
+    pricing?: Record<string, ModelPricing>;
+    costApprover?: CostApprover;
+    autoApproveBelowUsd?: number;
+    /** 테스트/대체용 LLM 호출 주입. 미지정 시 실제 llmComplete(키 필요). */
+    complete?: (prompt: string, system?: string) => Promise<string>;
+}
+export interface GovernedResult {
+    ok: boolean;
+    reason: string;
+    text?: string;
+    costUsd?: number;
+}
+export declare class GovernedExecutor {
+    private gov;
+    private opts;
+    constructor(gov: GovernanceController, opts?: GovernedExecutorOptions);
+    /**
+     * 거버넌스로 게이팅된 LLM 호출. 예상 토큰으로 비용을 추정해 승인·예산을 거친 뒤에만 실행한다.
+     */
+    llmCall(prompt: string, estTokensIn: number, estTokensOut: number, system?: string): Promise<GovernedResult>;
+    /** 임의의 비싼 행동을 거버넌스로 게이팅(킬스위치+예산). 비용 단위는 호출자 정의. */
+    guardedAction<T>(label: string, cost: number, run: () => Promise<T>): Promise<{
+        ok: boolean;
+        reason: string;
+        result?: T;
+    }>;
+}

package/dist/governed-executor.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GovernedExecutor = void 0;
+const cost_estimator_1 = require("./cost-estimator");
+const llm_1 = require("./llm");
+class GovernedExecutor {
+    gov;
+    opts;
+    constructor(gov, opts = {}) {
+        this.gov = gov;
+        this.opts = opts;
+    }
+    /**
+     * 거버넌스로 게이팅된 LLM 호출. 예상 토큰으로 비용을 추정해 승인·예산을 거친 뒤에만 실행한다.
+     */
+    async llmCall(prompt, estTokensIn, estTokensOut, system) {
+        const model = this.opts.model ?? 'claude-opus-4-8';
+        // 1) 킬스위치
+        if (this.gov.isKilled()) {
+            this.gov.record('blocked', 'llm-call (killswitch)');
+            return { ok: false, reason: 'killswitch active' };
+        }
+        // 2) 비용 견적 + 3) 승인 게이트
+        const est = (0, cost_estimator_1.estimateCost)(model, estTokensIn, estTokensOut, this.opts.pricing);
+        const approval = await (0, cost_estimator_1.requireCostApproval)(est, {
+            approve: this.opts.costApprover,
+            autoApproveBelowUsd: this.opts.autoApproveBelowUsd,
+        });
+        if (!approval.approved) {
+            this.gov.record('blocked', `llm-call (cost ${approval.reason})`);
+            return { ok: false, reason: `cost not approved: ${approval.reason}`, costUsd: est.costUsd };
+        }
+        // 4) 예산 인가(킬스위치 재확인 포함)
+        const auth = this.gov.authorize('llm-call', est.costUsd);
+        if (!auth.allowed) {
+            return { ok: false, reason: auth.reason, costUsd: est.costUsd };
+        }
+        // 5) 실제 실행
+        const complete = this.opts.complete ?? llm_1.llmComplete;
+        try {
+            const text = await complete(prompt, system);
+            this.gov.record('executed', `llm-call cost=${est.costUsd}`);
+            return { ok: true, reason: 'ok', text, costUsd: est.costUsd };
+        }
+        catch (err) {
+            this.gov.record('error', `llm-call ${err.message}`);
+            return { ok: false, reason: `execution error: ${err.message}`, costUsd: est.costUsd };
+        }
+    }
+    /** 임의의 비싼 행동을 거버넌스로 게이팅(킬스위치+예산). 비용 단위는 호출자 정의. */
+    async guardedAction(label, cost, run) {
+        if (this.gov.isKilled()) {
+            this.gov.record('blocked', `${label} (killswitch)`);
+            return { ok: false, reason: 'killswitch active' };
+        }
+        const auth = this.gov.authorize(label, cost);
+        if (!auth.allowed)
+            return { ok: false, reason: auth.reason };
+        const result = await run();
+        return { ok: true, reason: 'ok', result };
+    }
+}
+exports.GovernedExecutor = GovernedExecutor;

package/dist/governed-llm.d.ts

@@ -0,0 +1,41 @@
+import { ChatTurn } from './llm';
+import { Tier } from './tier-classifier';
+import { TierGuard } from './tier-guard';
+export interface GovernedBackends {
+    external: (history: ChatTurn[], system?: string) => Promise<string>;
+    local: (history: ChatTurn[], system?: string) => Promise<string>;
+    localConfigured: () => boolean;
+    externalAvailable: () => boolean;
+    externalName: () => string;
+}
+export interface GovernedResult {
+    text: string;
+    tier: Tier;
+    provider: 'local' | 'external' | 'none';
+    blockedExternal: boolean;
+    reason: string;
+}
+export declare const TIER0_NO_LOCAL_NOTICE = "[\uBCF4\uC548\u00B7Tier-0] \uBBFC\uAC10 \uB370\uC774\uD130(\uAC1C\uC778\uC815\uBCF4/\uC790\uACA9\uC99D\uBA85/\uC13C\uC11C\u00B7\uC74C\uC131)\uB294 \uC678\uBD80 \uBAA8\uB378\uB85C \uBCF4\uB0B4\uC9C0 \uC54A\uC2B5\uB2C8\uB2E4. \uB85C\uCEEC \uBAA8\uB378(OLLAMA_MODEL) \uBBF8\uC124\uC815\uC73C\uB85C \uCC98\uB9AC\uB97C \uBCF4\uB958\uD588\uC2B5\uB2C8\uB2E4 \u2014 \uB85C\uCEEC \uBAA8\uB378\uC744 \uC124\uC815\uD558\uBA74 \uCC98\uB9AC\uB429\uB2C8\uB2E4.";
+export declare const TIER1_NOTICE = "[Tier-1] \uC678\uBD80 \uBAA8\uB378 \uC0AC\uC6A9 \uB3D9\uC758\uAC00 \uC5C6\uACE0 \uB85C\uCEEC \uBAA8\uB378\uB3C4 \uC5C6\uC5B4 \uCC98\uB9AC\uB97C \uBCF4\uB958\uD588\uC2B5\uB2C8\uB2E4. \uB3D9\uC758(consent) \uB610\uB294 \uB85C\uCEEC \uBAA8\uB378\uC744 \uC124\uC815\uD558\uC138\uC694.";
+export declare const NO_BACKEND_NOTICE = "[\uC54C\uB9BC] \uC0AC\uC6A9 \uAC00\uB2A5\uD55C LLM \uBC31\uC5D4\uB4DC\uAC00 \uC5C6\uC2B5\uB2C8\uB2E4(\uC678\uBD80 \uD0A4\u00B7\uB85C\uCEEC \uBAA8\uB378 \uBAA8\uB450 \uBBF8\uC124\uC815).";
+/**
+ * Tier 라우팅 강제 에이전트. respond()가 실 실행 경로의 단일 강제 지점.
+ */
+export declare class GovernedAgent {
+    private backends;
+    private guard;
+    /** 채널 정책상 기준 Tier — *미분류(DEFAULT-DENY)*에만 적용. 민감 매칭은 항상 Tier-0 유지. */
+    private baselineTier?;
+    constructor(backends: GovernedBackends, opts?: {
+        guard?: TierGuard;
+        baselineTier?: Tier;
+    });
+    respond(history: ChatTurn[], opts?: {
+        consent?: boolean;
+        system?: string;
+        baselineTier?: Tier;
+    }): Promise<GovernedResult>;
+    guardRef(): TierGuard;
+}
+/** llm.ts 기반 기본 백엔드 구성(외부=askAgentChat, 로컬=localChat). */
+export declare function defaultGovernedBackends(runShell: (cmd: string) => Promise<string>): GovernedBackends;