@asc-agent/runtime 0.1.0

package/dist/adapters/text/renderer.d.ts

@@ -0,0 +1,7 @@
+import type { Rendered, RenderDensity, Renderer } from '../../ports/renderer.ts';
+import type { DecisionSummary, DecisionView } from '../../core/view/decision-view.ts';
+export declare class TextRenderer implements Renderer {
+    readonly id = "text";
+    renderDecision(view: DecisionView, density: RenderDensity): Rendered;
+    renderList(items: readonly DecisionSummary[]): Rendered;
+}

package/dist/adapters/text/renderer.js

@@ -0,0 +1,81 @@
+// 텍스트 Renderer — 터미널과 로그에 쓰는 기본 표현.
+//
+// 지키는 것 둘 (C-01 §2·§6):
+//   1. reference는 어떤 밀도에서도 첫 줄에 남는다. 다른 채널에서 같은 요청을 지목하는
+//      유일한 수단이라 접기의 대상이 아니다.
+//   2. 알림 당시 분석과 지금 다시 읽은 사실은 다른 제목 아래 놓는다. 한 문단에 섞으면
+//      읽는 사람이 과거 판단을 현재 사실로 받아들인다.
+/** 조회 시점에 무엇이 달라졌는지 한 줄로 알려준다 — 사용자가 먼저 읽어야 할 경고다. */
+const FRESHNESS_NOTE = {
+    CURRENT: '알림 이후 달라진 것 없음',
+    STALE_CONTEXT: '주의 — 알림 이후 작업 맥락이 바뀌었다',
+    SOURCE_CHANGED: '주의 — 알림 이후 원본(스레드·정본)이 바뀌었다',
+    ALREADY_DECIDED: '이미 결정된 요청이다',
+};
+/**
+ * 원본을 확인하지 못한 채 얻은 "변화 없음"을 확인하고 얻은 것처럼 보이게 두지 않는다.
+ * 무엇을 근거로 한 판단인지 밝히는 것이 판단 자체보다 중요할 때가 있다.
+ */
+function freshnessLine(view) {
+    const unverifiedSource = view.verification.source === 'UNAVAILABLE';
+    const scope = unverifiedSource && view.freshness === 'CURRENT' ? ' (로컬 기준)' : '';
+    const lines = [`상태: ${view.stored.status} (v${view.version})  ·  ${FRESHNESS_NOTE[view.freshness]}${scope}`];
+    if (unverifiedSource)
+        lines.push('원본 변경 여부 미확인 — 외부 연결 없음');
+    if (view.verification.localContext === 'NOT_APPLICABLE') {
+        lines.push('현재 작업과의 관계 판단 불가 — 요청이 영향 세션을 지목하지 않았다');
+    }
+    return lines;
+}
+export class TextRenderer {
+    id = 'text';
+    renderDecision(view, density) {
+        const lines = [view.reference, view.stored.title, ''];
+        lines.push(...freshnessLine(view));
+        if (view.decided) {
+            lines.push(`결정: ${view.decided.kind} — ${view.decided.actor} (${view.decided.channel}) ${view.decided.decidedAt}`);
+            if (view.resultRef)
+                lines.push(`결과: ${view.resultRef}`);
+        }
+        if (density === 'summary') {
+            lines.push('', `선택: ${view.allowedDecisions.join(' / ')}`);
+            return { density, text: lines.join('\n') };
+        }
+        lines.push('', '[알림 당시 분석]', `감지: ${view.stored.detectedAt} · ${view.stored.source}`, view.stored.situation);
+        if (view.stored.context)
+            lines.push('', `맥락: ${view.stored.context}`);
+        lines.push('', `작업 중단 필요: ${view.stored.interruptRequired ? 'Yes' : 'No'}`, `기준 세션: ${view.stored.affectedSessions.join(', ') || '없음'}`);
+        if (view.stored.rationale)
+            lines.push(`판단 근거: ${view.stored.rationale}`);
+        if (view.stored.snapshot.length > 0) {
+            lines.push('스냅샷: ' + view.stored.snapshot.map((s) => `${s.sourceId} @ ${s.baseline}`).join(' · '));
+        }
+        if (view.stored.recommendation)
+            lines.push('', `권장 대응: ${view.stored.recommendation}`);
+        if (view.stored.draft)
+            lines.push('', '[답변 초안]', view.stored.draft);
+        if (view.current) {
+            lines.push('', '[현재 작업 기준]', `관측: ${view.current.observedAt}`, `활성 세션: ${view.current.activeSessions.join(', ') || '없음'}`, `영향: ${view.current.affectsCurrentWork ? '있음' : '없음'}`);
+            for (const change of view.current.canonicalChanges) {
+                lines.push(`정본 변경: ${change.sourceId} ${change.before ?? '(기록 없음)'} → ${change.after}`);
+            }
+            for (const note of view.current.notes)
+                lines.push(`· ${note}`);
+        }
+        lines.push('', `승인 권한자: ${view.authorizedApprover}`, `선택: ${view.allowedDecisions.join(' / ')}`);
+        if (view.expiresAt)
+            lines.push(`만료: ${view.expiresAt}`);
+        return { density, text: lines.join('\n') };
+    }
+    renderList(items) {
+        if (items.length === 0)
+            return { density: 'summary', text: '대기 중인 요청 없음' };
+        const text = items
+            .map((i) => {
+            const stale = i.freshness === 'CURRENT' ? '' : `  [${i.freshness}]`;
+            return `${i.requestId}  ${i.priority}  ${i.status}  ${i.title}${stale}\n         ${i.reference}`;
+        })
+            .join('\n');
+        return { density: 'summary', text };
+    }
+}

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

@@ -0,0 +1,103 @@
+import { z } from 'zod';
+import type { ScopedStore } from '../../ports/state-store.ts';
+import type { Cursor, EventBatch, EventSource, RawEvent } from '../../ports/event-source.ts';
+export declare const IngressRecord: z.ZodObject<{
+    /** 수신 순번. drain은 이 순서로 돌려준다 — 도착 순서가 곧 관측 순서다. */
+    seq: z.ZodNumber;
+    receivedAt: z.ZodString;
+    event: z.ZodObject<{
+        eventKey: z.ZodString;
+        detectedAt: z.ZodString;
+        reference: z.ZodString;
+        hints: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+        raw: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        detectedAt: string;
+        eventKey: string;
+        reference: string;
+        raw?: unknown;
+        hints?: Record<string, unknown> | undefined;
+    }, {
+        detectedAt: string;
+        eventKey: string;
+        reference: string;
+        raw?: unknown;
+        hints?: Record<string, unknown> | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    event: {
+        detectedAt: string;
+        eventKey: string;
+        reference: string;
+        raw?: unknown;
+        hints?: Record<string, unknown> | undefined;
+    };
+    seq: number;
+    receivedAt: string;
+}, {
+    event: {
+        detectedAt: string;
+        eventKey: string;
+        reference: string;
+        raw?: unknown;
+        hints?: Record<string, unknown> | undefined;
+    };
+    seq: number;
+    receivedAt: string;
+}>;
+export type IngressRecord = z.infer<typeof IngressRecord>;
+export type VerifyOutcome = {
+    ok: true;
+} | {
+    ok: false;
+    reason: 'NO_SIGNATURE' | 'BAD_SIGNATURE';
+    detail: string;
+};
+/**
+ * HMAC 서명 확인 (C-12 불변식 ⑧).
+ *
+ * 길이가 달라도 같은 시간을 쓰도록 비교 전에 맞춘다 — 길이로 새는 정보도 정보다.
+ */
+export declare function verifySignature(payload: string, signature: string | undefined, secret: string): VerifyOutcome;
+export type AcceptOutcome = {
+    ok: true;
+    seq: number;
+} | {
+    ok: false;
+    reason: 'NO_SIGNATURE' | 'BAD_SIGNATURE' | 'UNREADABLE';
+    detail: string;
+};
+/**
+ * 받은 것을 쌓는다. **여기서 판정하지 않는다** — 분류·관련성·억제는 전부 기존 Phase A가 한다.
+ *
+ * 저장은 순번마다 다른 키에 setIfAbsent다. 읽고-고쳐-쓰면 동시에 도착한 둘 중 하나가
+ * 조용히 사라지는데, 그건 "변경 없음"으로 보인다.
+ */
+export declare class WebhookIngress {
+    #private;
+    constructor(scope: ScopedStore, secret: string, now?: () => string);
+    accept(payload: string, signature: string | undefined, toEvent: (parsed: unknown) => RawEvent | null): Promise<AcceptOutcome>;
+    /** 쌓인 것을 순서대로 꺼내고 지운다. 꺼낸 것은 Engine이 지고, 여기 남기지 않는다. */
+    drain(limit?: number): Promise<RawEvent[]>;
+    pending(): Promise<number>;
+    /** 튕긴 수. 0이 아니면 무언가 잘못 설정돼 있다는 뜻이고, 그건 감지 공백이다. */
+    rejected(): Promise<Record<string, number>>;
+}
+/**
+ * 버퍼를 비우는 EventSource. **Engine은 이것이 push인지 pull인지 모른다** —
+ * `ports/event-source.ts` 가 예고한 바로 그 형태다.
+ *
+ * cursor를 쓰지 않는다: 꺼낸 것은 지워지므로 다음 회차는 남은 것부터 본다. 중복은
+ * 기존 dedupe(eventKey exact lookup)가 거른다 — 같은 변경을 회수 경로가 다시 봐도
+ * 패킷이 둘이 되지 않는 이유와 같다.
+ */
+export declare class IngressEventSource implements EventSource {
+    #private;
+    readonly id: string;
+    constructor(deps: {
+        id?: string;
+        ingress: WebhookIngress;
+        limit?: number;
+    });
+    drain(_cursor: Cursor): Promise<EventBatch>;
+}

package/dist/adapters/webhook/ingress.js

@@ -0,0 +1,150 @@
+// Webhook Ingress — 밀려 들어오는 사건을 받아 두는 자리 (C-12 §2).
+//
+// Webhook은 새 개념이 아니다. C-07 §1.1이 Delta를 "webhook / incremental polling /
+// provider notification / updated-since" 로 이미 정의했고, `ports/event-source.ts` 는
+// **push형 Adapter는 수신분을 버퍼에 쌓아 두고 drain에서 돌려준다** 고 예고해 뒀다.
+// 이 파일은 그 예고를 실제로 구현할 뿐이며 MonitorEngine은 한 줄도 바뀌지 않는다.
+//
+// 책임을 둘로 나눈다 (C-12 불변식 ⑦):
+//
+//   Ingress     받는다 · 검증한다 · 쌓는다        ← 이 파일
+//   Orchestrator 언제 처리할지 정한다              ← core/runtime/orchestrator.ts
+//
+// 지금은 같은 프로세스에 둘 수 있지만 Core는 그 배치를 모른다. 나중에 receiver만
+// 떼어내도 계약은 그대로다.
+//
+// **서명 검증은 생략할 수 없다** (불변식 ⑧). 검증 실패는 조용한 무시가 아니라 거부이며,
+// 거부한 사실도 기록에 남는다 — 아무도 안 오는 것과 오는데 다 튕기는 것은 다른 상태다.
+import { createHmac, timingSafeEqual } from 'node:crypto';
+import { z } from 'zod';
+export const IngressRecord = z.object({
+    /** 수신 순번. drain은 이 순서로 돌려준다 — 도착 순서가 곧 관측 순서다. */
+    seq: z.number().int().positive(),
+    receivedAt: z.string().min(1),
+    event: z.object({
+        eventKey: z.string().min(1),
+        detectedAt: z.string().min(1),
+        reference: z.string().min(1),
+        hints: z.record(z.unknown()).optional(),
+        raw: z.unknown().optional(),
+    }),
+});
+const bufferKey = (seq) => `ingress:${String(seq).padStart(12, '0')}`;
+const BUFFER_PREFIX = 'ingress:';
+const REJECTED_KEY = 'ingress-rejected';
+/**
+ * HMAC 서명 확인 (C-12 불변식 ⑧).
+ *
+ * 길이가 달라도 같은 시간을 쓰도록 비교 전에 맞춘다 — 길이로 새는 정보도 정보다.
+ */
+export function verifySignature(payload, signature, secret) {
+    if (!signature)
+        return { ok: false, reason: 'NO_SIGNATURE', detail: '서명 헤더가 없다' };
+    const expected = createHmac('sha256', secret).update(payload).digest('hex');
+    // provider마다 `sha256=` 같은 접두어를 붙인다. 값만 본다.
+    const given = signature.includes('=') ? signature.slice(signature.indexOf('=') + 1) : signature;
+    const a = Buffer.from(expected, 'utf8');
+    const b = Buffer.from(given, 'utf8');
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+        return { ok: false, reason: 'BAD_SIGNATURE', detail: '서명이 맞지 않는다' };
+    }
+    return { ok: true };
+}
+/**
+ * 받은 것을 쌓는다. **여기서 판정하지 않는다** — 분류·관련성·억제는 전부 기존 Phase A가 한다.
+ *
+ * 저장은 순번마다 다른 키에 setIfAbsent다. 읽고-고쳐-쓰면 동시에 도착한 둘 중 하나가
+ * 조용히 사라지는데, 그건 "변경 없음"으로 보인다.
+ */
+export class WebhookIngress {
+    #scope;
+    #secret;
+    #now;
+    constructor(scope, secret, now = () => new Date().toISOString()) {
+        this.#scope = scope;
+        this.#secret = secret;
+        this.#now = now;
+    }
+    async accept(payload, signature, toEvent) {
+        const verified = verifySignature(payload, signature, this.#secret);
+        if (!verified.ok) {
+            // 튕긴 것도 사실이다. 아무도 안 오는 것과 오는데 다 튕기는 것을 구분해야 한다.
+            await this.#countRejected(verified.reason);
+            return { ok: false, reason: verified.reason, detail: verified.detail };
+        }
+        let event;
+        try {
+            event = toEvent(JSON.parse(payload));
+        }
+        catch (error) {
+            await this.#countRejected('UNREADABLE');
+            return { ok: false, reason: 'UNREADABLE', detail: error instanceof Error ? error.message : String(error) };
+        }
+        if (!event) {
+            // 이 provider 사건은 우리가 아는 형태가 아니다 — 지어내지 않는다
+            await this.#countRejected('UNREADABLE');
+            return { ok: false, reason: 'UNREADABLE', detail: '읽을 수 있는 사건이 아니다' };
+        }
+        let seq = (await this.#lastSeq()) + 1;
+        for (;;) {
+            const record = IngressRecord.parse({ seq, receivedAt: this.#now(), event });
+            if (await this.#scope.setIfAbsent(bufferKey(seq), JSON.stringify(record)))
+                return { ok: true, seq };
+            seq += 1;
+        }
+    }
+    /** 쌓인 것을 순서대로 꺼내고 지운다. 꺼낸 것은 Engine이 지고, 여기 남기지 않는다. */
+    async drain(limit = 100) {
+        const keys = (await this.#scope.keys(BUFFER_PREFIX)).sort().slice(0, limit);
+        const events = [];
+        for (const key of keys) {
+            const raw = await this.#scope.get(key);
+            if (!raw)
+                continue;
+            const parsed = IngressRecord.safeParse(JSON.parse(raw));
+            // 깨진 항목은 판정 근거가 못 된다 — 그 항목만 버린다
+            if (parsed.success)
+                events.push(parsed.data.event);
+            await this.#scope.delete(key);
+        }
+        return events;
+    }
+    async pending() {
+        return (await this.#scope.keys(BUFFER_PREFIX)).length;
+    }
+    /** 튕긴 수. 0이 아니면 무언가 잘못 설정돼 있다는 뜻이고, 그건 감지 공백이다. */
+    async rejected() {
+        const raw = await this.#scope.get(REJECTED_KEY);
+        return raw ? JSON.parse(raw) : {};
+    }
+    async #countRejected(reason) {
+        const current = await this.rejected();
+        await this.#scope.set(REJECTED_KEY, JSON.stringify({ ...current, [reason]: (current[reason] ?? 0) + 1 }));
+    }
+    async #lastSeq() {
+        const keys = await this.#scope.keys(BUFFER_PREFIX);
+        return keys.reduce((max, key) => Math.max(max, Number(key.slice(BUFFER_PREFIX.length)) || 0), 0);
+    }
+}
+/**
+ * 버퍼를 비우는 EventSource. **Engine은 이것이 push인지 pull인지 모른다** —
+ * `ports/event-source.ts` 가 예고한 바로 그 형태다.
+ *
+ * cursor를 쓰지 않는다: 꺼낸 것은 지워지므로 다음 회차는 남은 것부터 본다. 중복은
+ * 기존 dedupe(eventKey exact lookup)가 거른다 — 같은 변경을 회수 경로가 다시 봐도
+ * 패킷이 둘이 되지 않는 이유와 같다.
+ */
+export class IngressEventSource {
+    id;
+    #ingress;
+    #limit;
+    constructor(deps) {
+        this.id = deps.id ?? 'webhook-ingress';
+        this.#ingress = deps.ingress;
+        this.#limit = deps.limit ?? 100;
+    }
+    async drain(_cursor) {
+        const events = await this.#ingress.drain(this.#limit);
+        return { events, cursor: null, hasMore: (await this.#ingress.pending()) > 0 };
+    }
+}

package/dist/cli/asc.d.ts

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+/**
+ * 어느 문으로 들어왔는가 (C-14 §3.4).
+ *
+ * **`bootstrap` 만 stable runtime 설치를 계획한다.** 설치된 runtime이 스스로를 다시
+ * 설치하는 것은 말이 안 되고, 그것을 계획에 넣으면 매 setup이 npm을 부른다.
+ */
+export type AscEntry = 'runtime' | 'bootstrap';
+/**
+ * CLI 한 번의 실행. **다른 진입도 이 함수를 부른다** (C-14 불변식 ①).
+ *
+ * bootstrap 패키지는 아직 아무것도 설치되지 않은 machine에서 이것을 그대로 부른다 —
+ * 진입이 둘이어도 판단은 하나다. 그래서 export이고, 그래서 아래 자동 실행은 이 파일이
+ * 진짜 진입점일 때만 돈다.
+ */
+export declare function runAscCommand(argv: string[], entry?: AscEntry): Promise<number>;