@bevel-software/platform-shared 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/dist/auth/types.d.ts

@@ -0,0 +1,15 @@
+export interface AuthUser {
+    id: string;
+    email: string;
+    name: string;
+    avatarUrl?: string;
+}
+export interface LoginRequest {
+    email: string;
+    password: string;
+}
+export interface LoginResponse {
+    token: string;
+    user: AuthUser;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/auth/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;CAChB"}

package/dist/auth/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/auth/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/auth/types.ts"],"names":[],"mappings":""}

package/dist/chat/types.d.ts

@@ -0,0 +1,39 @@
+import type { UIMessage } from 'ai';
+import type { AuthUser } from '../auth/types.js';
+/**
+ * Domain-owned alias for the AI SDK v5 UIMessage shape.
+ *
+ * Backend and frontend both import `ChatUIMessage` rather than `UIMessage`
+ * directly so the seam is renameable if the SDK type shifts.
+ */
+export type ChatUIMessage = UIMessage;
+export interface ChatThread {
+    id: string;
+    title: string;
+    createdAt: number;
+    updatedAt: number;
+}
+export declare const COMPACTION_SOFT_LIMIT_TOKENS = 200000;
+export declare const COMPACTION_HARD_LIMIT_TOKENS = 350000;
+/** Per-turn token usage attached to the assistant message via a `data-usage` part. */
+export interface UsagePartData {
+    used: number;
+    softLimit: number;
+    hardLimit: number;
+}
+export interface IChatService {
+    streamResponse(params: {
+        message: string;
+        resourceId: string;
+        threadId: string;
+        workspaceId: string;
+        /**
+         * Required — the agent authors every git commit as the user, and the
+         * author marker it pastes into PR bodies is derived from the user's email.
+         * Backend reads `user.name` and `user.email` unconditionally.
+         */
+        user: AuthUser;
+        abortSignal?: AbortSignal;
+    }): Promise<ReadableStream<unknown>>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/chat/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/chat/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,IAAI,CAAC;AACpC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,CAAC;AAEtC,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAYD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AACpD,eAAO,MAAM,4BAA4B,SAAU,CAAC;AAEpD,sFAAsF;AACtF,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,YAAY;IAC3B,cAAc,CAAC,MAAM,EAAE;QACrB,OAAO,EAAE,MAAM,CAAC;QAChB,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,WAAW,EAAE,MAAM,CAAC;QACpB;;;;WAIG;QACH,IAAI,EAAE,QAAQ,CAAC;QACf,WAAW,CAAC,EAAE,WAAW,CAAC;KAC3B,GAAG,OAAO,CAAC,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC;CACtC"}

package/dist/chat/types.js

@@ -0,0 +1,13 @@
+// Calibrated for gpt-5.1 (~400k context) with current agent.instructions.ts size
+// + typical KB file tree. Lower than the raw window because the system prompt
+// and workspace state occupy ~40-80k before the user types. Re-tune if the
+// model changes or the system prompt grows materially.
+//
+// Both thresholds drive the agent's input processors in BaseAgentFactory:
+//   - softLimit  → SummaryCompactor recaps the middle of the transcript
+//   - hardLimit  → TokenLimiterProcessor backstops with truncation
+// The composer's context-usage gauge also reads these via the UsagePartData
+// emitted at end-of-turn.
+export const COMPACTION_SOFT_LIMIT_TOKENS = 200_000;
+export const COMPACTION_HARD_LIMIT_TOKENS = 350_000;
+//# sourceMappingURL=types.js.map

package/dist/chat/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/chat/types.ts"],"names":[],"mappings":"AAkBA,iFAAiF;AACjF,8EAA8E;AAC9E,2EAA2E;AAC3E,uDAAuD;AACvD,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,mEAAmE;AACnE,4EAA4E;AAC5E,0BAA0B;AAC1B,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC;AACpD,MAAM,CAAC,MAAM,4BAA4B,GAAG,OAAO,CAAC"}

package/dist/git/branchAuthor.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Derive the kebab-cased branch-author localpart from an email.
+ *
+ * The frontend's `slugifyDraftName` lowercases the email's localpart and
+ * replaces non-alphanumeric runs with `-` when building a new branch name
+ * (e.g. `Alice@example.com` → `alice/<slug>`, `john.doe@…` → `john-doe/…`).
+ * Authorship lookup must use the same transformation so a branch the user
+ * could create via the UI is also recognised as theirs on delete.
+ *
+ * Returns `null` when the email is missing or sanitizes to an empty string —
+ * authorship MUST NOT silently fall back to a default identity like `user`.
+ * If the helper returned a fallback, any user without a valid localpart
+ * would be granted ownership of every `user/...` branch on origin, which is
+ * the opposite of the safety property `isBranchAuthoredBy` is meant to
+ * provide. The frontend's `slugifyDraftName` can keep its UI-side `user`
+ * fallback at the call site because draft creation is not access-gated.
+ */
+export declare function branchAuthorLocalpart(email: string | null | undefined): string | null;
+/**
+ * True when `branchName` starts with `<email-localpart>/` — i.e. when the
+ * branch matches the UI-created draft convention for this user.
+ *
+ * The trailing `/` is REQUIRED: without it, `alice-extra/foo` would look
+ * authored by `alice@…`, and any user could delete branches whose prefix
+ * happens to start with their own localpart. Substring is not authorship.
+ */
+export declare function isBranchAuthoredBy(branchName: string, email: string | null | undefined): boolean;
+//# sourceMappingURL=branchAuthor.d.ts.map

package/dist/git/branchAuthor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"branchAuthor.d.ts","sourceRoot":"","sources":["../../src/git/branchAuthor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,MAAM,GAAG,IAAI,CASf;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAChC,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC/B,OAAO,CAIT"}

package/dist/git/branchAuthor.js

@@ -0,0 +1,45 @@
+/**
+ * Derive the kebab-cased branch-author localpart from an email.
+ *
+ * The frontend's `slugifyDraftName` lowercases the email's localpart and
+ * replaces non-alphanumeric runs with `-` when building a new branch name
+ * (e.g. `Alice@example.com` → `alice/<slug>`, `john.doe@…` → `john-doe/…`).
+ * Authorship lookup must use the same transformation so a branch the user
+ * could create via the UI is also recognised as theirs on delete.
+ *
+ * Returns `null` when the email is missing or sanitizes to an empty string —
+ * authorship MUST NOT silently fall back to a default identity like `user`.
+ * If the helper returned a fallback, any user without a valid localpart
+ * would be granted ownership of every `user/...` branch on origin, which is
+ * the opposite of the safety property `isBranchAuthoredBy` is meant to
+ * provide. The frontend's `slugifyDraftName` can keep its UI-side `user`
+ * fallback at the call site because draft creation is not access-gated.
+ */
+export function branchAuthorLocalpart(email) {
+    if (!email)
+        return null;
+    const before = email.split('@')[0];
+    if (!before)
+        return null;
+    const sanitized = before.toLowerCase().replace(/[^a-z0-9]+/g, '-');
+    // Sanitized can be all dashes (`-`, `--`) when every char was non-alphanumeric;
+    // treat that as no usable identity.
+    if (!sanitized.replace(/-/g, ''))
+        return null;
+    return sanitized;
+}
+/**
+ * True when `branchName` starts with `<email-localpart>/` — i.e. when the
+ * branch matches the UI-created draft convention for this user.
+ *
+ * The trailing `/` is REQUIRED: without it, `alice-extra/foo` would look
+ * authored by `alice@…`, and any user could delete branches whose prefix
+ * happens to start with their own localpart. Substring is not authorship.
+ */
+export function isBranchAuthoredBy(branchName, email) {
+    const localpart = branchAuthorLocalpart(email);
+    if (!localpart)
+        return false;
+    return branchName.startsWith(`${localpart}/`);
+}
+//# sourceMappingURL=branchAuthor.js.map

package/dist/git/branchAuthor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"branchAuthor.js","sourceRoot":"","sources":["../../src/git/branchAuthor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAgC;IAEhC,IAAI,CAAC,KAAK;QAAE,OAAO,IAAI,CAAC;IACxB,MAAM,MAAM,GAAG,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IACzB,MAAM,SAAS,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC,CAAC;IACnE,gFAAgF;IAChF,oCAAoC;IACpC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,kBAAkB,CAChC,UAAkB,EAClB,KAAgC;IAEhC,MAAM,SAAS,GAAG,qBAAqB,CAAC,KAAK,CAAC,CAAC;IAC/C,IAAI,CAAC,SAAS;QAAE,OAAO,KAAK,CAAC;IAC7B,OAAO,UAAU,CAAC,UAAU,CAAC,GAAG,SAAS,GAAG,CAAC,CAAC;AAChD,CAAC"}

package/dist/git/pr.types.d.ts

@@ -0,0 +1,264 @@
+export type PullRequestState = 'open' | 'merged' | 'closed';
+export interface PullRequestAuthor {
+    login: string;
+    name?: string;
+}
+export interface PullRequestReviewStatus {
+    approvals: number;
+    changesRequested: number;
+    /** GitHub logins of reviewers with a pending request (no review yet). */
+    pendingLogins: string[];
+}
+export interface PullRequestSummary {
+    number: number;
+    title: string;
+    author: PullRequestAuthor;
+    /**
+     * Opaque SHA-256 hash of the authoring user's email. Embedded in the PR body via a hidden
+     * marker so `/pr/mine` can filter by identity without leaking raw emails into bodies. Absent
+     * on PRs not created through this backend. `author.login` is always the GitHub account that
+     * actually opened the PR (typically our service account). Compare by re-hashing the caller's
+     * email; there is no reverse lookup.
+     */
+    authorId?: string;
+    /**
+     * The app user (not the GitHub account) who triggered this PR. Resolved server-side by
+     * matching `authorId` against the hash of every app user's email. Use this in user-facing
+     * surfaces — `author.login` is always the shared service account.
+     *
+     * Display name only — no email. Other authenticated workspace members don't need raw
+     * emails to render PR attribution. The hash in `authorId` is the stable identity if
+     * downstream code needs to compare against the current user.
+     *
+     * Absent when no app user matches the hash (e.g. PRs opened outside this backend, or after
+     * an app user was removed from the users table).
+     */
+    appAuthor?: {
+        name: string;
+    };
+    branch: string;
+    base: string;
+    state: PullRequestState;
+    createdAt: string;
+    /** Relative paths within `knowledge-base/`. Empty if not yet computed. */
+    touchedNodePaths: string[];
+    review: PullRequestReviewStatus;
+    url: string;
+}
+export type PrFileStatus = 'added' | 'modified' | 'removed' | 'renamed' | 'copied' | 'changed' | 'unchanged';
+/**
+ * A single file in a PR. Patch is GitHub's unified-diff text; it's absent for
+ * binary files and for files larger than the API cutoff (~3 MB). `previousPath`
+ * is populated for renames/copies.
+ */
+export interface PullRequestFile {
+    path: string;
+    previousPath?: string;
+    status: PrFileStatus;
+    additions: number;
+    deletions: number;
+    patch?: string;
+    isBinary: boolean;
+    /** Blob SHA at the PR head — stable identifier for caching raw content. */
+    sha: string;
+    /** Authenticated `raw.githubusercontent.com`-style URL for the blob at head. */
+    rawUrl: string;
+}
+/**
+ * One comment in the Bevel-owned PR discussion. GitHub never sees these —
+ * they live only in our DB, attributed to the authenticated user. Shape
+ * encodes three comment kinds:
+ *
+ *   General         → path undefined, line undefined
+ *   File-level      → path set,      line undefined
+ *   Inline (line)   → path set,      line set
+ *
+ * Threading: `parentId` points at the root of the thread; top-level comments
+ * have it undefined.
+ */
+export interface PrReviewComment {
+    id: string;
+    author: {
+        email: string;
+        name: string;
+    };
+    body: string;
+    path?: string;
+    line?: number;
+    /** The head SHA the comment was authored against — lets the UI grey out stale inline pins. */
+    headSha: string;
+    parentId?: string;
+    createdAt: string;
+    updatedAt?: string;
+}
+export interface PostPrCommentInput {
+    body: string;
+    path?: string;
+    line?: number;
+    parentId?: string;
+}
+/**
+ * One owner's approval on one file. Stored straight from the
+ * `pr_file_approvals` row, with derived flags the UI needs.
+ */
+export interface FileApprovalEntry {
+    email: string;
+    name: string;
+    approvedAt: string;
+    /** True when this approval was captured against a SHA that is no longer the PR head. */
+    isStale: boolean;
+    /** True when the approver is the PR author (hash-matched against the PR body marker). */
+    isSelfApproval: boolean;
+}
+/**
+ * Per-file approval state the PR viewer needs to render the approval badge,
+ * the Approve button, and the merge gate.
+ *
+ * `eligibleApprovers` lists everyone who could approve this file at the PR
+ * head SHA, derived from the access tree (`roles.yaml` + `access.md`). A
+ * file is approved when any non-author user holding one of those roles (or
+ * directly named) submits a non-stale approval. The built-in role `everyone`
+ * means any signed-in approver is eligible.
+ */
+export interface FileApprovalState {
+    path: string;
+    /**
+     * Roles + direct user grants that confer write access on this file as of
+     * the PR head. `roles` may include the built-in role `everyone`. Empty roles
+     * + empty users means the file is outside the access-controlled surface (no
+     * rule grants write); the merge gate silently excludes such entries instead
+     * of blocking on them.
+     */
+    eligibleApprovers: {
+        roles: string[];
+        users: {
+            name: string;
+            email: string;
+        }[];
+    };
+    approvedBy: FileApprovalEntry[];
+    /**
+     * True iff at least one eligible approver has submitted a non-stale
+     * approval. Always `false` when `eligibleApprovers` is empty — with no
+     * eligible set, nobody can satisfy the check.
+     * Whether the gate *cares* about this file is a separate concern handled
+     * by the merge-gate logic: non-md files and files with no eligible
+     * approvers are silently excluded from the gate, so `isApproved: false`
+     * on one of them does not block merge.
+     */
+    isApproved: boolean;
+    /**
+     * Pre-computed for the requesting viewer: would `approveFile` accept their
+     * click? True iff their email resolves to `write` on this path under the
+     * access tree at `origin/<baseBranch>`. The frontend uses this to gate the
+     * Approve button — without it, the button shows for any user whenever the
+     * eligible-roles list is non-empty, which is misleading because most users
+     * aren't actually in those roles. Backend remains authoritative; this is a
+     * UX hint, not a security boundary.
+     */
+    viewerCanApprove: boolean;
+}
+/**
+ * Full read-only PR detail for the in-app viewer. Extends the summary with
+ * body, SHAs, file list, and the Bevel-owned comments. Later phases add
+ * `approvals` and merge-gate fields — this shape grows incrementally.
+ */
+export interface PullRequestDetail extends PullRequestSummary {
+    body: string;
+    headSha: string;
+    baseSha: string;
+    files: PullRequestFile[];
+    comments: PrReviewComment[];
+    /**
+     * One entry per file in `files`, same order. Empty when the caller had no
+     * resolvable workspace to do the owner lookup against.
+     */
+    approvals: FileApprovalState[];
+    /**
+     * True iff no *hard* block applies — the PR is open, has files, and isn't
+     * merged/closed. Soft warnings (missing owner approvals on md files) do
+     * **not** set this to false; the UI handles them via the bypass dialog.
+     * The button is disabled only when this is false.
+     */
+    mergeableInBevel: boolean;
+    /**
+     * Hard-block reasons — merging is impossible until these resolve (PR state,
+     * no files, etc.). Empty when the PR can be merged (possibly after bypass).
+     */
+    mergeBlockedReasons: string[];
+    /**
+     * Soft warnings — md files with an owner who hasn't approved (or whose
+     * approval is stale). Merging is allowed but the UI asks for an explicit
+     * bypass confirmation first. Non-md files and ownerless md files are silent.
+     */
+    mergeWarnings: string[];
+    /**
+     * True iff the viewer holds write on `roles.yaml` at `origin/<base>` —
+     * i.e. they're in the Admin role on the canonical access tree. The
+     * frontend uses this to hide / disable the bypass action for non-admins;
+     * the backend enforces the same check on the merge route. False when no
+     * viewer was passed (anonymous detail fetch) or when the access tree on
+     * base can't be resolved.
+     */
+    viewerCanBypassMerge: boolean;
+    /**
+     * True iff the viewer is allowed to cancel this change request: the PR is
+     * open AND the viewer is either its author (hash-matched against the body
+     * marker) or an admin (write on `roles.yaml` at `origin/<base>` — same
+     * predicate `viewerCanBypassMerge` uses). The frontend renders the Cancel
+     * button as disabled when this is false; the backend re-checks server-side
+     * on `POST /pr/:n/cancel`, so this is a UX hint, not a security boundary.
+     * False when no viewer was passed, the state isn't `open`, or the access
+     * tree can't be resolved.
+     */
+    viewerCanCancel: boolean;
+}
+/**
+ * Result of a successful merge via the in-app gate. `sha` is the merge commit
+ * GitHub produced; the UI uses it to link to the resulting commit and to
+ * invalidate any stale views.
+ */
+export interface MergePrResult {
+    prNumber: number;
+    sha: string;
+    mergedAt: string;
+}
+/**
+ * Result of a successful cancel via `POST /pr/:n/cancel`. No SHA — closing a
+ * PR without merging produces no merge commit. `cancelledAt` is the
+ * server-side timestamp the close was recorded; useful for audit display.
+ */
+export interface CancelPrResult {
+    prNumber: number;
+    cancelledAt: string;
+}
+export interface IPullRequestService {
+    /**
+     * `opts.fresh` bypasses the internal 30s list cache — used when the UI has
+     * a reason to believe the server-side state just changed (agent-opened PR
+     * via `gh pr create`) and the user expects to see the update immediately.
+     */
+    listOpenPrs(opts?: {
+        fresh?: boolean;
+    }): Promise<PullRequestSummary[]>;
+    listPrsAuthoredBy(githubLoginOrEmail: string): Promise<PullRequestSummary[]>;
+    /**
+     * PRs whose touched paths have an owner with the given email.
+     * Resolution uses the given workspace's KB — caller passes their own workspaceId.
+     */
+    listPrsForOwnerEmail(workspaceId: string, email: string, opts?: {
+        fresh?: boolean;
+    }): Promise<PullRequestSummary[]>;
+    getPr(prNumber: number): Promise<PullRequestSummary | null>;
+    /**
+     * Full detail for the in-app PR viewer. `opts.fresh` bypasses the detail cache
+     * — use for event-driven refreshes (post-merge, share-dialog create).
+     * `opts.viewerEmail` pre-computes `viewerCanApprove` per file.
+     */
+    getPrDetail(prNumber: number, opts?: {
+        fresh?: boolean;
+        workspaceId?: string;
+        viewerEmail?: string;
+    }): Promise<PullRequestDetail | null>;
+}
+//# sourceMappingURL=pr.types.d.ts.map

package/dist/git/pr.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr.types.d.ts","sourceRoot":"","sources":["../../src/git/pr.types.ts"],"names":[],"mappings":"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"}

package/dist/git/pr.types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=pr.types.js.map

package/dist/git/pr.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pr.types.js","sourceRoot":"","sources":["../../src/git/pr.types.ts"],"names":[],"mappings":""}