@asc-agent/runtime 0.1.0

package/dist/adapters/github/context.js

@@ -0,0 +1,170 @@
+// GitHub Context Adapters — Inventory · ResourceContext · ChangeContext (C-09 §2).
+//
+// 세 Port를 한 파일에 두는 이유는 같은 client와 같은 참조 문법을 쓰기 때문이다.
+// 인터페이스는 셋으로 나뉘어 있으므로 소비자는 필요한 것만 받는다.
+//
+// revisionMarker는 여기서 만든다 — 무엇이 실질 변화인지는 provider가 아는 사실이고,
+// Core는 그 값을 비교만 한다 (C-07 §4.2).
+import { parseThreadRef } from "./scm.js";
+const labelNames = (labels) => (labels ?? []).map((l) => (typeof l === 'string' ? l : (l.name ?? ''))).filter((n) => n.length > 0);
+/**
+ * 실질 변화 마커. 갱신 시각 하나로는 댓글 외의 변화를 놓치므로 여러 조각을 묶는다
+ * (C-07 §4.2 — 무엇을 넣을지는 adapter가 정한다).
+ */
+const marker = (parts) => parts.map((p) => (p === undefined ? '' : String(p))).join('|');
+class GitHubContextBase {
+    id = 'github';
+    client;
+    defaultRepo;
+    constructor(deps) {
+        this.client = deps.client;
+        this.defaultRepo = deps.defaultRepo;
+    }
+    expand(reference) {
+        const trimmed = reference.trim();
+        return trimmed.startsWith('#') && this.defaultRepo ? `${this.defaultRepo}${trimmed}` : trimmed;
+    }
+}
+/**
+ * 상태 무관 열거 (C-09 §2). `state=all`이 이 Port의 존재 이유다 —
+ * 닫힌 것을 빼면 닫힌 뒤에 일어난 일을 통째로 놓친다.
+ *
+ * GitHub은 PR도 issues 목록에 실어 주므로 한 번의 열거로 둘 다 덮인다.
+ * 그래서 `kinds`를 받아도 별도 호출로 나누지 않고 결과에서 가른다.
+ */
+export class GitHubInventory extends GitHubContextBase {
+    #pageSize;
+    constructor(deps) {
+        super(deps);
+        this.#pageSize = deps.pageSize ?? 100;
+    }
+    async enumerate(query, cursor) {
+        if (!this.defaultRepo) {
+            // 어디를 열거할지 모른다. 빈 목록을 "없다"로 돌려주면 census가 전부 사라졌다고 본다.
+            return { items: [], complete: false };
+        }
+        const page = cursor ? Number(cursor) : 1;
+        const params = new URLSearchParams({
+            state: 'all',
+            per_page: String(this.#pageSize),
+            page: String(page),
+            sort: 'updated',
+            direction: 'desc',
+        });
+        if (query.updatedSince)
+            params.set('since', query.updatedSince);
+        const response = await this.client.get(`/repos/${this.defaultRepo}/issues?${params}`);
+        // 못 읽었으면 complete=false다. 페이지를 다 돌지 못했는데 끝인 척하면
+        // Census가 "사라졌다"를 잘못 만들어낸다 (C-07 §1.5).
+        if (!response.ok || !response.data)
+            return { items: [], complete: false };
+        const wanted = new Set(query.kinds ?? []);
+        const items = [];
+        for (const issue of response.data) {
+            const kind = issue.pull_request ? 'change' : 'issue';
+            if (wanted.size > 0 && !wanted.has(kind))
+                continue;
+            items.push({
+                reference: `${this.defaultRepo}#${issue.number}`,
+                state: issue.state,
+                updatedAt: issue.updated_at,
+                revisionMarker: marker([issue.updated_at, issue.comments, issue.state]),
+                title: issue.title,
+                assignees: (issue.assignees ?? []).map((a) => a.login),
+                labels: labelNames(issue.labels),
+            });
+        }
+        const full = response.data.length === this.#pageSize;
+        return {
+            items,
+            ...(full ? { next: String(page + 1) } : {}),
+            // 마지막 페이지에서만 완주를 말한다 (ports/inventory.ts 계약).
+            complete: !full,
+        };
+    }
+}
+export class GitHubResourceContext extends GitHubContextBase {
+    async getResource(reference) {
+        const ref = parseThreadRef(this.expand(reference));
+        if (!ref)
+            return missingResource(reference);
+        const response = await this.client.get(`/repos/${ref.owner}/${ref.repo}/issues/${ref.number}`);
+        if (!response.ok || !response.data)
+            return missingResource(reference);
+        const issue = response.data;
+        return {
+            reference,
+            state: issue.state,
+            title: issue.title,
+            ...(issue.body ? { body: issue.body } : {}),
+            ...(issue.user?.login ? { author: issue.user.login } : {}),
+            assignees: (issue.assignees ?? []).map((a) => a.login),
+            labels: labelNames(issue.labels),
+            updatedAt: issue.updated_at,
+            revisionMarker: marker([issue.updated_at, issue.comments, issue.state]),
+        };
+    }
+    /**
+     * 최근 것부터. 전문을 통째로 넘기지 않는 것이 이 Port의 계약이므로 개수를 호출자가 정한다
+     * — 조사 depth가 예산을 쥔다 (C-05 §3).
+     */
+    async getComments(reference, query = {}) {
+        const ref = parseThreadRef(this.expand(reference));
+        if (!ref)
+            return [];
+        const params = new URLSearchParams({ per_page: String(query.limit ?? 20), sort: 'created', direction: 'desc' });
+        if (query.since)
+            params.set('since', query.since);
+        const response = await this.client.get(`/repos/${ref.owner}/${ref.repo}/issues/${ref.number}/comments?${params}`);
+        if (!response.ok || !response.data)
+            return [];
+        return response.data.map((comment) => ({
+            id: String(comment.id),
+            author: comment.user?.login ?? '(unknown)',
+            at: comment.updated_at ?? comment.created_at,
+            body: comment.body ?? '',
+            // unresolved 여부를 이 API가 말해주지 않는다. 모르는 것을 false로 적지 않는다.
+        }));
+    }
+}
+export class GitHubChangeContext extends GitHubContextBase {
+    #pageSize;
+    constructor(deps) {
+        super(deps);
+        this.#pageSize = deps.pageSize ?? 100;
+    }
+    async getChange(reference) {
+        const ref = parseThreadRef(this.expand(reference));
+        if (!ref)
+            return { reference, changedPaths: [], revisionMarker: '', missing: true };
+        const base = `/repos/${ref.owner}/${ref.repo}/pulls/${ref.number}`;
+        const pull = await this.client.get(base);
+        if (!pull.ok || !pull.data) {
+            // 변경요청이 아니거나 못 읽었다. 둘 다 "경로가 없다"가 아니라 "모른다"이다.
+            return { reference, changedPaths: [], revisionMarker: '', missing: true };
+        }
+        const files = await this.client.get(`${base}/files?per_page=${this.#pageSize}`);
+        const paths = (files.data ?? []).map((f) => f.filename);
+        // 한 페이지를 꽉 채웠으면 뒤가 더 있을 수 있다. 그 사실을 숨기면
+        // "내 영역은 안 바뀌었다"는 틀린 판정이 나온다.
+        const truncated = paths.length === this.#pageSize || !files.ok;
+        const reviews = await this.client.get(`${base}/reviews?per_page=20`);
+        const reviewState = (reviews.data ?? []).at(-1)?.state;
+        return {
+            reference,
+            changedPaths: paths,
+            ...(truncated ? { truncated: true } : {}),
+            ...(pull.data.head?.sha ? { revisions: [pull.data.head.sha] } : {}),
+            revisionMarker: marker([pull.data.updated_at, pull.data.head?.sha, pull.data.state, reviewState]),
+            ...(reviewState ? { reviewState } : {}),
+        };
+    }
+}
+const missingResource = (reference) => ({
+    reference,
+    state: 'unknown',
+    title: '',
+    updatedAt: '',
+    revisionMarker: '',
+    missing: true,
+});

package/dist/adapters/github/event-source.d.ts

@@ -0,0 +1,55 @@
+import type { Cursor, EventBatch, EventSource } from '../../ports/event-source.ts';
+import type { GitHubClient } from './client.ts';
+/**
+ * cursor에 담기는 것. 엔드포인트마다 기준선이 달라 한 값으로 못 묶는다.
+ * 문자열로 직렬화해 Port 계약(Cursor = string | null)에 맞춘다.
+ *
+ * `since`는 경계를 포함하므로 마지막 항목이 다음 회차에 다시 온다. 그대로 둔다 —
+ * 1초를 밀어 중복을 없애면 같은 시각에 달린 다른 댓글이 통째로 사라진다.
+ * 누락보다 중복이 안전하고, 중복은 event key exact lookup이 거른다 (OM §10.5).
+ *
+ * `page`는 한 배치가 perPage를 꽉 채웠을 때만 세워진다. 같은 시각 이벤트가 한 페이지를
+ * 넘겨도 다음 회차가 이어서 받도록 하는 장치다.
+ */
+export type GitHubCursor = {
+    notificationsSince?: string;
+    notificationsLastModified?: string;
+    notificationsPage?: number;
+    commentsSince?: string;
+    commentsPage?: number;
+    reviewCommentsSince?: string;
+    reviewCommentsPage?: number;
+};
+export declare function parseCursor(cursor: Cursor): GitHubCursor;
+export type GitHubEventSourceDeps = {
+    client: GitHubClient;
+    /** `owner/repo`. 알림도 댓글도 이 저장소 것만 본다. */
+    repo: string;
+    /** 한 번에 가져올 최대 개수. 폭주해도 한 배치가 감당 가능한 크기로 끊는다. */
+    perPage?: number;
+};
+export declare class GitHubEventSource implements EventSource {
+    #private;
+    readonly id = "github-poll";
+    constructor(deps: GitHubEventSourceDeps);
+    /** 세 갈래 모두 같은 시점부터 본다. 페이지 상태는 비워 둔다 — 아직 아무것도 읽지 않았다. */
+    cursorFrom(since: string): Cursor;
+    drain(cursor: Cursor): Promise<EventBatch>;
+}
+/**
+ * GitHub notification의 `reason` 어휘를 Generic Signal로 옮기는 매핑.
+ *
+ * Core에 두지 않는 이유는 이것이 GitHub의 말이기 때문이다. `mention`·`review_requested`는
+ * 이 provider가 쓰는 단어이고, 다른 곳은 다른 단어를 쓴다. Adapter가 자기 어휘를 내놓고
+ * Profile이 그것을 고르면, Core는 끝까지 신호의 이름만 알면 된다 (OM §10.6).
+ */
+export declare const GITHUB_REASON_SIGNALS: {
+    readonly assign: "assigned_to_me";
+    readonly mention: "mentioned_me";
+    readonly team_mention: "mentioned_me";
+    readonly review_requested: "review_requested";
+    readonly author: "my_pr_reviewed";
+    readonly comment: "participated_thread_changed";
+    readonly subscribed: "participated_thread_changed";
+    readonly state_change: "participated_thread_changed";
+};

package/dist/adapters/github/event-source.js

@@ -0,0 +1,183 @@
+// GitHub polling Event Source.
+//
+// 하는 일은 "무슨 일이 있었는지" 모아 오는 것까지다. 무엇이 중요한지, 누구에게 알릴지는
+// Monitor가 정한다 (B-09) — 여기서 우선순위를 매기기 시작하면 Profile 없이 프로젝트
+// 사정을 아는 Adapter가 되어버린다.
+//
+// cursor는 호출자가 갱신한다. Phase B가 중간에 실패했을 때 cursor를 전진시키지 않고
+// 다시 받는 편이 안전하기 때문이다 — 누락보다 중복이 낫고, 중복은 event key가 거른다
+// (OM §10.5).
+/**
+ * 다음 조회를 어디서부터 시작할지. 마지막 항목보다 조금 **뒤로** 잡는다.
+ *
+ * `since`는 그 시각 이후를 주므로, 마지막 항목의 시각을 그대로 쓰면 그 직후 같은 초에
+ * 달린 이벤트가 영영 안 온다. 앞으로 미는 것(bump)은 더 나쁘고, 정확히 맞추는 것도
+ * 초 단위 경계에서는 불가능하다. 그래서 조금 겹쳐 읽고 중복은 key로 거른다.
+ */
+const OVERLAP_MS = 1000;
+function watermark(timestamp) {
+    return new Date(new Date(timestamp).getTime() - OVERLAP_MS).toISOString();
+}
+/**
+ * 한 페이지를 읽고 나서 기준선과 페이지를 어떻게 옮길지 정한다.
+ * 꽉 찬 페이지는 뒤가 더 있다는 뜻이므로 기준선을 건드리지 않고 페이지만 넘긴다 —
+ * 같은 시각 이벤트가 페이지 경계에 걸려도 잃지 않는다.
+ */
+function advance(rowCount, perPage, since, page, lastTimestamp) {
+    if (rowCount >= perPage)
+        return { ...(since !== undefined ? { since } : {}), page: page + 1 };
+    if (lastTimestamp !== undefined)
+        return { since: watermark(lastTimestamp) };
+    return since !== undefined ? { since } : {};
+}
+export function parseCursor(cursor) {
+    if (!cursor)
+        return {};
+    try {
+        return JSON.parse(cursor);
+    }
+    catch {
+        return {};
+    }
+}
+export class GitHubEventSource {
+    id = 'github-poll';
+    #client;
+    #repo;
+    #perPage;
+    constructor(deps) {
+        this.#client = deps.client;
+        this.#repo = deps.repo;
+        this.#perPage = deps.perPage ?? 50;
+    }
+    /** 세 갈래 모두 같은 시점부터 본다. 페이지 상태는 비워 둔다 — 아직 아무것도 읽지 않았다. */
+    cursorFrom(since) {
+        return JSON.stringify({ notificationsSince: since, commentsSince: since, reviewCommentsSince: since });
+    }
+    async drain(cursor) {
+        const state = parseCursor(cursor);
+        const events = [];
+        const next = { ...state };
+        // 1. 알림 — mention·assign·review_requested가 여기로 온다.
+        //    전역이 아니라 저장소 한정으로 묻는다. `.asc/`는 프로젝트마다 따로 있으므로
+        //    다른 저장소의 알림이 이 Runtime에 섞이면 안 된다 (OM §3.2).
+        //    all=true인 이유는 감지가 사람의 읽음 처리에 좌우되면 안 되기 때문이다 —
+        //    GitHub 웹에서 먼저 읽었다는 이유로 Monitor가 그 사건을 놓치면 안 된다.
+        const notificationPage = state.notificationsPage ?? 1;
+        const notifications = await this.#client.get(`/repos/${this.#repo}/notifications?all=true&per_page=${this.#perPage}&page=${notificationPage}` +
+            (state.notificationsSince ? `&since=${state.notificationsSince}` : ''), 
+        // 페이지를 이어받는 중이면 조건부 요청을 쓰지 않는다. 304가 오면 남은 페이지를
+        // 영영 못 받기 때문이다.
+        state.notificationsLastModified && state.notificationsPage === undefined
+            ? { ifModifiedSince: state.notificationsLastModified }
+            : {});
+        if (notifications.ok && notifications.data) {
+            for (const item of notifications.data) {
+                events.push({
+                    eventKey: `notification:${item.id}:${item.updated_at}`,
+                    detectedAt: item.updated_at,
+                    reference: referenceOf(item),
+                    hints: { actors: [], labels: [] },
+                    raw: { kind: 'notification', reason: item.reason, subjectType: item.subject.type, title: item.subject.title },
+                });
+            }
+            const rows = notifications.data;
+            const moved = advance(rows.length, this.#perPage, state.notificationsSince, notificationPage, rows.at(-1)?.updated_at);
+            if (moved.since !== undefined)
+                next.notificationsSince = moved.since;
+            if (moved.page === undefined)
+                delete next.notificationsPage;
+            else
+                next.notificationsPage = moved.page;
+            // 마지막 페이지까지 읽었을 때만 조건부 요청 기준을 갱신한다
+            if (notifications.lastModified && moved.page === undefined) {
+                next.notificationsLastModified = notifications.lastModified;
+            }
+        }
+        // 2. 이슈 댓글 — 알림이 오지 않는 참여 스레드의 움직임까지 본다
+        const comments = await this.#drainComments('issues', state.commentsSince, state.commentsPage);
+        for (const comment of comments.rows) {
+            events.push({
+                eventKey: `comment:${comment.id}`,
+                detectedAt: comment.updated_at,
+                reference: issueRefOf(comment, this.#repo),
+                hints: { actors: comment.user ? [comment.user.login] : [] },
+                raw: { kind: 'issue_comment', url: comment.html_url, body: comment.body },
+            });
+        }
+        if (comments.read) {
+            if (comments.since !== undefined)
+                next.commentsSince = comments.since;
+            if (comments.page === undefined)
+                delete next.commentsPage;
+            else
+                next.commentsPage = comments.page;
+        }
+        // 3. PR 리뷰 댓글 — 코드 줄에 달린 것들
+        const reviewComments = await this.#drainComments('pulls', state.reviewCommentsSince, state.reviewCommentsPage);
+        for (const comment of reviewComments.rows) {
+            events.push({
+                eventKey: `review_comment:${comment.id}`,
+                detectedAt: comment.updated_at,
+                reference: pullRefOf(comment, this.#repo),
+                hints: { actors: comment.user ? [comment.user.login] : [] },
+                raw: { kind: 'review_comment', url: comment.html_url, body: comment.body },
+            });
+        }
+        if (reviewComments.read) {
+            if (reviewComments.since !== undefined)
+                next.reviewCommentsSince = reviewComments.since;
+            if (reviewComments.page === undefined)
+                delete next.reviewCommentsPage;
+            else
+                next.reviewCommentsPage = reviewComments.page;
+        }
+        // review 제출(승인/변경요청) 자체는 여기서 긁지 않는다. 본인이 관련된 것은 알림으로
+        // 들어오고, 그 밖의 것까지 보려면 열린 PR을 전부 순회해야 해서 값이 비싸다.
+        // 필요해지면 `/repos/{repo}/pulls/{n}/reviews`로 `review:<id>` key를 만든다.
+        events.sort((a, b) => a.detectedAt.localeCompare(b.detectedAt));
+        const hasMore = next.notificationsPage !== undefined ||
+            next.commentsPage !== undefined ||
+            next.reviewCommentsPage !== undefined;
+        return { events, cursor: JSON.stringify(next), hasMore };
+    }
+    /** 댓글 한 페이지를 받고 기준선을 옮긴다 (`advance` 참조). */
+    async #drainComments(kind, since, page) {
+        const current = page ?? 1;
+        const response = await this.#client.get(`/repos/${this.#repo}/${kind}/comments?per_page=${this.#perPage}&sort=updated&direction=asc&page=${current}` +
+            (since ? `&since=${since}` : ''));
+        if (!response.ok || !response.data)
+            return { read: false, rows: [] };
+        const rows = response.data;
+        return { read: true, rows, ...advance(rows.length, this.#perPage, since, current, rows.at(-1)?.updated_at) };
+    }
+}
+function referenceOf(item) {
+    const number = item.subject.url?.match(/\/(\d+)$/)?.[1];
+    return number ? `${item.repository.full_name}#${number}` : item.repository.full_name;
+}
+function issueRefOf(comment, repo) {
+    const number = comment.issue_url?.match(/\/(\d+)$/)?.[1];
+    return number ? `${repo}#${number}` : repo;
+}
+function pullRefOf(comment, repo) {
+    const number = comment.pull_request_url?.match(/\/(\d+)$/)?.[1];
+    return number ? `${repo}#${number}` : repo;
+}
+/**
+ * GitHub notification의 `reason` 어휘를 Generic Signal로 옮기는 매핑.
+ *
+ * Core에 두지 않는 이유는 이것이 GitHub의 말이기 때문이다. `mention`·`review_requested`는
+ * 이 provider가 쓰는 단어이고, 다른 곳은 다른 단어를 쓴다. Adapter가 자기 어휘를 내놓고
+ * Profile이 그것을 고르면, Core는 끝까지 신호의 이름만 알면 된다 (OM §10.6).
+ */
+export const GITHUB_REASON_SIGNALS = {
+    assign: 'assigned_to_me',
+    mention: 'mentioned_me',
+    team_mention: 'mentioned_me',
+    review_requested: 'review_requested',
+    author: 'my_pr_reviewed',
+    comment: 'participated_thread_changed',
+    subscribed: 'participated_thread_changed',
+    state_change: 'participated_thread_changed',
+};

package/dist/adapters/github/scm.d.ts

@@ -0,0 +1,50 @@
+import type { CanonicalSnapshot } from '../../core/model/entities.ts';
+import type { BaselineQuery, ExternalAction, ExternalActionResult, ScmPort, ThreadSnapshot } from '../../ports/scm.ts';
+import type { GitHubClient } from './client.ts';
+/** `owner/repo#19` 를 쪼갠다. 다른 형태는 다루지 않는다. */
+export declare function parseThreadRef(reference: string): {
+    owner: string;
+    repo: string;
+    number: number;
+} | null;
+export type GitHubScmDeps = {
+    client: GitHubClient;
+    /** `owner/repo`. 짧은 참조(`#19`)를 풀 때 쓴다. */
+    defaultRepo?: string;
+    /** canonical source id → git ref. Profile이 채운다 (OM §8). */
+    sourceRefs?: Readonly<Record<string, {
+        owner?: string;
+        repo?: string;
+        ref: string;
+    }>>;
+};
+export declare class GitHubScm implements ScmPort {
+    #private;
+    readonly id = "github";
+    constructor(deps: GitHubScmDeps);
+    /**
+     * 스레드의 현재 상태를 하나의 표식으로 만든다. Drift Guard가 이 값으로 "승인 이후 뭔가
+     * 달라졌는가"를 판단하므로, 조회가 실패하면 변화 없음으로 넘기지 않고 missing으로
+     * 돌려준다 — 모르면 실행하지 않는 쪽이 맞다 (OM §11.9).
+     *
+     * 표식은 세 조각을 묶는다:
+     *   issue의 updated_at  — 제목·본문 수정을 잡는다
+     *   댓글 수             — 추가·삭제를 잡는다
+     *   마지막 댓글의 id·updated_at — 새 댓글과 그 수정을 잡는다
+     *
+     * 마지막 댓글은 `per_page=1&page=<댓글 수>`로 직접 집는다. 첫 page만 보면 댓글이 100개를
+     * 넘는 순간 새 댓글을 못 보고 오래된 초안이 그대로 나간다.
+     *
+     * ponytail: 중간 댓글 하나만 수정된 경우는 이 표식으로 잡히지 않는다. 전부 잡으려면
+     * 모든 댓글을 훑어 해시를 내야 하는데 스레드마다 매번 그러기엔 비싸다. 필요해지면
+     * 마지막 N개만 해시하는 쪽으로 좁혀서 올린다.
+     */
+    getThread(reference: string): Promise<ThreadSnapshot>;
+    /** source별 현재 baseline. 하나라도 못 읽으면 그 source는 `unknown`으로 남는다. */
+    getBaselines(queries: readonly BaselineQuery[]): Promise<CanonicalSnapshot[]>;
+    /**
+     * 승인된 단일 행위. 아는 action만 수행하며, 그 외에는 아무것도 하지 않는다 —
+     * Grant의 allowedWrites 검사(Executor)에 더해 Adapter도 자기 몫으로 닫아 둔다.
+     */
+    execute(action: ExternalAction): Promise<ExternalActionResult>;
+}

package/dist/adapters/github/scm.js

@@ -0,0 +1,104 @@
+// GitHub SCM Adapter — 스레드·정본 조회와, 승인된 단일 행위의 실행.
+//
+// 쓰기는 `execute` 하나뿐이고, 그 함수는 Grant를 쥔 Executor만 부른다 (OM §11.5).
+// Adapter는 권한을 판단하지 않는다 — 판단은 이미 끝났고 여기는 실행만 한다.
+// 대신 Grant가 지정한 action 밖의 일은 하지 않는다: 아는 행위가 아니면 거절한다.
+/** `owner/repo#19` 를 쪼갠다. 다른 형태는 다루지 않는다. */
+export function parseThreadRef(reference) {
+    const match = /^([^/\s]+)\/([^#\s]+)#(\d+)$/.exec(reference.trim());
+    if (!match)
+        return null;
+    return { owner: match[1], repo: match[2], number: Number(match[3]) };
+}
+export class GitHubScm {
+    id = 'github';
+    #client;
+    #defaultRepo;
+    #sourceRefs;
+    constructor(deps) {
+        this.#client = deps.client;
+        this.#defaultRepo = deps.defaultRepo;
+        this.#sourceRefs = deps.sourceRefs ?? {};
+    }
+    /**
+     * 스레드의 현재 상태를 하나의 표식으로 만든다. Drift Guard가 이 값으로 "승인 이후 뭔가
+     * 달라졌는가"를 판단하므로, 조회가 실패하면 변화 없음으로 넘기지 않고 missing으로
+     * 돌려준다 — 모르면 실행하지 않는 쪽이 맞다 (OM §11.9).
+     *
+     * 표식은 세 조각을 묶는다:
+     *   issue의 updated_at  — 제목·본문 수정을 잡는다
+     *   댓글 수             — 추가·삭제를 잡는다
+     *   마지막 댓글의 id·updated_at — 새 댓글과 그 수정을 잡는다
+     *
+     * 마지막 댓글은 `per_page=1&page=<댓글 수>`로 직접 집는다. 첫 page만 보면 댓글이 100개를
+     * 넘는 순간 새 댓글을 못 보고 오래된 초안이 그대로 나간다.
+     *
+     * ponytail: 중간 댓글 하나만 수정된 경우는 이 표식으로 잡히지 않는다. 전부 잡으려면
+     * 모든 댓글을 훑어 해시를 내야 하는데 스레드마다 매번 그러기엔 비싸다. 필요해지면
+     * 마지막 N개만 해시하는 쪽으로 좁혀서 올린다.
+     */
+    async getThread(reference) {
+        const ref = parseThreadRef(this.#expand(reference));
+        if (!ref)
+            return { reference, lastEventId: '', missing: true };
+        const base = `/repos/${ref.owner}/${ref.repo}/issues/${ref.number}`;
+        const issue = await this.#client.get(base);
+        if (!issue.ok || !issue.data)
+            return { reference, lastEventId: '', missing: true };
+        const count = issue.data.comments;
+        const marker = `issue:${issue.data.updated_at}|c${count}`;
+        if (count === 0)
+            return { reference, lastEventId: marker };
+        const last = await this.#client.get(`${base}/comments?per_page=1&page=${count}`);
+        if (!last.ok || !last.data) {
+            // 댓글이 있다는데 못 읽었다. 안다고 답할 수 없으므로 실행을 막는다.
+            return { reference, lastEventId: '', missing: true };
+        }
+        const tail = last.data.at(-1);
+        return {
+            reference,
+            lastEventId: tail ? `${marker}|${tail.id}:${tail.updated_at}` : marker,
+        };
+    }
+    /** source별 현재 baseline. 하나라도 못 읽으면 그 source는 `unknown`으로 남는다. */
+    async getBaselines(queries) {
+        const out = [];
+        for (const query of queries) {
+            const configured = this.#sourceRefs[query.sourceId];
+            const ref = query.ref ?? configured?.ref;
+            const repo = this.#repoOf(configured);
+            if (!ref || !repo) {
+                out.push({ sourceId: query.sourceId, baseline: 'unknown' });
+                continue;
+            }
+            const response = await this.#client.get(`/repos/${repo}/commits/${encodeURIComponent(ref)}`);
+            const sha = response.data?.sha ?? response.data?.object?.sha;
+            out.push({ sourceId: query.sourceId, baseline: sha ?? 'unknown' });
+        }
+        return out;
+    }
+    /**
+     * 승인된 단일 행위. 아는 action만 수행하며, 그 외에는 아무것도 하지 않는다 —
+     * Grant의 allowedWrites 검사(Executor)에 더해 Adapter도 자기 몫으로 닫아 둔다.
+     */
+    async execute(action) {
+        if (action.action !== 'github.issue_comment.create') {
+            return { ok: false, error: `unsupported action: ${action.action}` };
+        }
+        const ref = parseThreadRef(this.#expand(action.target));
+        if (!ref)
+            return { ok: false, error: `unrecognized target: ${action.target}` };
+        const response = await this.#client.post(`/repos/${ref.owner}/${ref.repo}/issues/${ref.number}/comments`, { body: action.payload });
+        if (!response.ok || !response.data)
+            return { ok: false, error: response.error ?? `HTTP ${response.status}` };
+        return { ok: true, resultRef: response.data.html_url };
+    }
+    #expand(reference) {
+        return reference.startsWith('#') && this.#defaultRepo ? `${this.#defaultRepo}${reference}` : reference;
+    }
+    #repoOf(configured) {
+        if (configured?.owner && configured.repo)
+            return `${configured.owner}/${configured.repo}`;
+        return this.#defaultRepo ?? null;
+    }
+}

package/dist/adapters/gitlab/adapter.d.ts

@@ -0,0 +1,36 @@
+import type { AdapterDescriptor, BindingCandidate } from '../../core/binding/types.ts';
+import type { Adapter, DiscoveryContext, ProbeResult } from '../../ports/adapter.ts';
+export type GitLabAdapterDeps = {
+    listRemotes?: (projectRoot: string) => Promise<string[]>;
+    findToken?: (env?: NodeJS.ProcessEnv) => string | null;
+    reach?: (project: string, token: string) => Promise<{
+        ok: boolean;
+        detail?: string;
+    }>;
+    /**
+     * 명시 override. **필수가 아니다** — 기본은 remote에서 host를 읽는다.
+     * 자체 호스팅 주소를 코드나 문서에 박지 않기 위해서다 (지시 §12).
+     */
+    host?: string;
+};
+export declare class GitLabAdapter implements Adapter {
+    #private;
+    constructor(deps?: GitLabAdapterDeps);
+    describe(): AdapterDescriptor;
+    /**
+     * remote **전부**를 본다. `origin` 하나만 보면 origin이 코드 정본이 아닌 프로젝트에서
+     * 아무것도 못 찾는다 (지시 §13).
+     *
+     * host를 미리 알고 있지 않다 — 자체 호스팅이 흔하고, 주소를 코드에 박으면 그 프로젝트
+     * 하나를 위한 adapter가 된다. 대신 **다른 adapter가 맡는 host만 비켜** 나머지를 후보로
+     * 올린다. 후보는 추측이 아니라 후보이며, 실제로 되는지는 probe가 정한다.
+     */
+    discover(context: DiscoveryContext): Promise<BindingCandidate[]>;
+    probe(candidate: BindingCandidate, context: DiscoveryContext): Promise<ProbeResult>;
+    /** 이 후보가 어느 주소를 가리키는지. composition이 Port를 만들 때 같은 값을 써야 한다. */
+    endpointFor(resource: string): string | undefined;
+}
+export declare function parseRemote(url: string): {
+    host: string;
+    project: string;
+} | null;