@geminixiang/mikan 1.0.0-beta.7 → 1.0.0-beta.71

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

@@ -0,0 +1,345 @@
+import type { ConversationEvent } from "../index.js";
+import type { Workspace } from "../../office/types.js";
+export interface GithubEvent extends ConversationEvent {
+    type: "message" | "issue";
+    userName?: string;
+}
+export interface GithubBotConfig {
+    appId: string;
+    /** PEM-encoded GitHub App private key. */
+    privateKey: string;
+    installationId: string;
+    /** `owner/repo` entries to watch; empty = all installation repositories. */
+    repos: string[];
+    pollIntervalMs: number;
+    workspace: Workspace;
+    /**
+     * Where the poll watermark state (baseline + seen ids) is persisted. Lives
+     * under the host-only state dir: the workspace dir can be mounted into
+     * sandboxes, and sandboxed code must not be able to clear dedup state and
+     * re-trigger runs.
+     */
+    syncStatePath: string;
+}
+/** Persisted per-repo poll watermark (DESIGN.md § Event source). */
+interface GithubRepoSyncState {
+    /** Comments/issues created before this ISO instant never trigger. */
+    baseline: string;
+    /** Newest updated_at seen; polls fetch from (cursor - overlap). */
+    cursor: string;
+    seenComments: number[];
+    seenIssues: number[];
+    /** Optional so state files written before review-comment polling still load. */
+    seenReviewComments?: number[];
+}
+export interface GithubSyncState {
+    repos: Record<string, GithubRepoSyncState>;
+}
+export interface GithubRepoRef {
+    owner: string;
+    repo: string;
+}
+export interface GithubConversationRef extends GithubRepoRef {
+    number: number;
+}
+interface GithubUser {
+    login: string;
+    type: string;
+}
+export interface GithubIssue {
+    id: number;
+    number: number;
+    title: string;
+    body: string | null;
+    user: GithubUser;
+    created_at: string;
+    updated_at: string;
+    pull_request?: object;
+    /** open | closed */
+    state?: string;
+    labels?: {
+        name: string;
+    }[];
+    assignees?: {
+        login: string;
+    }[];
+}
+export interface GithubIssueComment {
+    id: number;
+    body: string;
+    user: GithubUser;
+    created_at: string;
+    updated_at: string;
+    /** API URL of the parent issue, e.g. …/repos/o/r/issues/42 */
+    issue_url: string;
+}
+/** An inline PR review comment (a comment on a diff line). */
+export interface GithubReviewComment {
+    id: number;
+    body: string;
+    user: GithubUser;
+    created_at: string;
+    updated_at: string;
+    /** API URL of the parent PR, e.g. …/repos/o/r/pulls/42 */
+    pull_request_url: string;
+    /** File the comment is anchored to. */
+    path: string;
+    /** Line in the diff's right side; null when the anchor is outdated. */
+    line: number | null;
+    /** The diff excerpt the comment is anchored to. */
+    diff_hunk: string;
+    /** Set on replies: the id of the thread's root comment. */
+    in_reply_to_id?: number;
+}
+export interface GithubRepository {
+    name: string;
+    owner: GithubUser;
+}
+export interface GithubRepositoryDetails {
+    default_branch: string;
+}
+export interface GithubCollaboratorPermission {
+    /** Legacy field: admin | write | read | none (maintain→write, triage→read). */
+    permission: string;
+    /** Granular assigned role (admin/maintain/write/triage/read or a custom role). */
+    role_name?: string;
+}
+export interface GithubPullRequest {
+    number: number;
+    html_url: string;
+    /** head.repo is null when the fork a PR came from was deleted. */
+    head?: {
+        ref: string;
+        sha: string;
+        repo?: {
+            full_name?: string;
+        } | null;
+    };
+    base?: {
+        ref: string;
+    };
+    title?: string;
+    body?: string | null;
+    /** open | closed */
+    state?: string;
+    draft?: boolean;
+    merged?: boolean;
+    mergeable_state?: string;
+    changed_files?: number;
+    additions?: number;
+    deletions?: number;
+    user?: GithubUser;
+}
+/** One row of GET /pulls/{n}/files. */
+export interface GithubPullRequestFile {
+    filename: string;
+    /** added | removed | modified | renamed | … */
+    status: string;
+    additions: number;
+    deletions: number;
+}
+/** One submitted review of GET /pulls/{n}/reviews. */
+export interface GithubPullRequestReview {
+    id: number;
+    user: GithubUser;
+    body: string | null;
+    /** APPROVED | CHANGES_REQUESTED | COMMENTED | DISMISSED | PENDING */
+    state: string;
+    submitted_at?: string;
+}
+export interface GithubCheckRun {
+    /** Check-run id; for GitHub Actions this doubles as the job id (log fetch). */
+    id: number;
+    name: string;
+    /** queued | in_progress | completed */
+    status: string;
+    /** success | failure | neutral | cancelled | skipped | timed_out | action_required | null while running */
+    conclusion: string | null;
+    html_url: string | null;
+    /** The app that reported the check (github-actions vs external CI). */
+    app?: {
+        slug?: string;
+    } | null;
+    /** Whatever the reporting app posted about the run. */
+    output?: {
+        title?: string | null;
+        summary?: string | null;
+    } | null;
+}
+/** Permission subset requestable on a scoped installation token. */
+export type GithubTokenPermissions = Partial<Record<"contents" | "pull_requests" | "issues", "read" | "write">>;
+export type GithubReactionContent = "+1" | "-1" | "laugh" | "confused" | "heart" | "hooray" | "rocket" | "eyes";
+export interface CloneRepoOptions {
+    /** HTTPS remote, e.g. https://github.com/owner/repo.git (no credentials). */
+    url: string;
+    /** Destination directory (the conversation dir's `repo/`). */
+    dir: string;
+    /** Ephemeral scoped installation token; used per-invocation, never stored. */
+    token: string;
+    botLogin: string;
+    botEmail: string;
+    /** When the conversation is a PR: fetch and check out its head. */
+    prNumber?: number;
+    /**
+     * The PR's head branch name when it lives in this repo (not a fork): the
+     * checkout is named after it so committing there + github_pr updates the
+     * PR in place. Absent (fork/unknown), the checkout falls back to pr-<n>.
+     */
+    prHeadBranch?: string;
+}
+export interface PushBranchOptions {
+    dir: string;
+    branch: string;
+    token: string;
+}
+export interface SyncRepoOptions {
+    dir: string;
+    /** Ephemeral contents:read token; used per-invocation, never stored. */
+    token: string;
+    /** Explicit branch to fetch; wins over prNumber/defaultBranch. */
+    branch?: string;
+    /** PR conversations: fetch pull/<n>/head into the local PR checkout. */
+    prNumber?: number;
+    /** Same-repo PR head name; the local checkout target. Fallback: pr-<n>. */
+    prHeadBranch?: string;
+    /** Fallback target when neither branch nor prNumber applies. */
+    defaultBranch?: string;
+}
+export interface SyncRepoResult {
+    /** Local branch the fetch targets (the PR head name, pr-<n>, or the branch). */
+    target: string;
+    fetchedSha: string;
+    /** True when the checkout was moved to the fetched head. */
+    updatedCheckout: boolean;
+    /** Working tree had uncommitted changes (checkout left alone). */
+    dirty: boolean;
+    currentBranch: string;
+    /** Bot-committed (agent-made) commits on the target that origin lacks. */
+    localCommits: number;
+}
+export interface GithubClientOptions {
+    appId: string;
+    privateKey: string;
+    installationId: string;
+    /** Override the API root for tests; defaults to https://api.github.com */
+    baseUrl?: string;
+    fetchImpl?: typeof fetch;
+}
+/** Arguments for the host-side `github_pr` tool. */
+export interface GithubPrRequest {
+    /** Local branch in the conversation's ./repo clone; must match pi/<name>. */
+    branch: string;
+    title: string;
+    body?: string;
+    /** Target branch; defaults to the repository's default branch. */
+    base?: string;
+    draft?: boolean;
+}
+export interface GithubPrResult {
+    number: number;
+    url: string;
+    /** True when the branch already had an open PR that this push updated. */
+    updatedExisting?: boolean;
+}
+/** Normalized check-run row for the host-side `github_checks` tool. */
+export interface GithubCheckSummary {
+    /** Check-run id; for GitHub Actions checks it is also the job id for log fetch. */
+    id: number;
+    name: string;
+    /** queued | in_progress | completed */
+    status: string;
+    /** success | failure | … ; null while the run is still in progress */
+    conclusion: string | null;
+    url: string | null;
+    /** Slug of the reporting app; "github-actions" checks have fetchable logs. */
+    appSlug: string | null;
+    /** The reporting app's own summary of the run, when it posted one. */
+    outputSummary: string | null;
+}
+export interface GithubChecksFns {
+    getChecks: (branch?: string) => Promise<GithubCheckSummary[]>;
+    getJobLog: (jobId: number) => Promise<string>;
+}
+/** Arguments for the host-side `github_read` tool. */
+export interface GithubReadRequest {
+    action: "pr" | "pr_files" | "pr_reviews" | "issue" | "comments" | "list";
+    /** Issue/PR number; defaults to the conversation's own. */
+    number?: number;
+    /** list only: open | closed | all (default open). */
+    state?: string;
+    /** list only: comma-separated label names. */
+    labels?: string;
+    /** list only: filter by author login. */
+    creator?: string;
+}
+/** Typed payload of one `github_read` action; the tool renders it. */
+export type GithubReadResult = {
+    kind: "pr";
+    pr: GithubPullRequest;
+} | {
+    kind: "pr_files";
+    files: GithubPullRequestFile[];
+} | {
+    kind: "pr_reviews";
+    reviews: GithubPullRequestReview[];
+    threads: GithubReviewComment[];
+} | {
+    kind: "issue";
+    issue: GithubIssue;
+} | {
+    kind: "comments";
+    comments: GithubIssueComment[];
+} | {
+    kind: "list";
+    issues: GithubIssue[];
+};
+/** Arguments for the host-side `github_issue` tool. Deliberately a closed
+ *  action set: lock/delete/transfer are not offered at all. */
+export interface GithubIssueRequest {
+    action: "add_labels" | "remove_label" | "add_assignees" | "remove_assignees" | "close" | "reopen";
+    /** Issue/PR number; defaults to the conversation's own (triage may target others). */
+    number?: number;
+    /** add_labels */
+    labels?: string[];
+    /** remove_label */
+    label?: string;
+    /** add_assignees / remove_assignees */
+    assignees?: string[];
+    /** close */
+    state_reason?: "completed" | "not_planned";
+}
+/**
+ * Host-side GitHub operations for github_* tools. Wired in main.ts over the
+ * GitHub bot; tokens stay host-side. Consumed by `createGithubToolPack`.
+ */
+export type GithubSyncFn = (branch?: string) => Promise<string>;
+export type GithubReviewReplyFn = (commentId: number, body: string) => Promise<{
+    url: string;
+}>;
+export type GithubReadFn = (request: GithubReadRequest) => Promise<GithubReadResult>;
+export type GithubIssueFn = (request: GithubIssueRequest) => Promise<string>;
+export interface PlatformGithubOps {
+    /** Push a prepared pi/* branch and open (or update) a pull request. */
+    pushAndCreatePr(conversationId: string, request: GithubPrRequest): Promise<GithubPrResult>;
+    /** CI check runs for a branch, or for the conversation's PR head when omitted. */
+    getChecks(conversationId: string, branch?: string): Promise<GithubCheckSummary[]>;
+    /** Log text of one CI job (an Actions check-run id), tail-truncated. */
+    getJobLog(conversationId: string, jobId: number): Promise<string>;
+    /** Reply inside one inline review thread of the conversation's PR. */
+    replyToReviewThread(conversationId: string, commentId: number, body: string): Promise<{
+        url: string;
+    }>;
+    /** Refresh the conversation's ./repo clone; returns a human-readable report. */
+    syncRepo(conversationId: string, branch?: string): Promise<string>;
+    /** Read PR/issue metadata the clone cannot provide; same repo only. */
+    readGithub(conversationId: string, request: GithubReadRequest): Promise<GithubReadResult>;
+    /** Label/assignee/state management on this repo's issues; returns a report. */
+    manageIssue(conversationId: string, request: GithubIssueRequest): Promise<string>;
+}
+export interface GithubWebhookOptions {
+    secret: string;
+    /** Called after signature verification for relevant events. */
+    onPoke: () => void;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/dist/adapters/github/types.d.ts.map

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

package/dist/adapters/github/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/adapters/github/types.ts"],"names":[],"mappings":"","sourcesContent":["import type { ConversationEvent } from \"../index.js\";\nimport type { Workspace } from \"../../office/types.js\";\n\nexport interface GithubEvent extends ConversationEvent {\n  type: \"message\" | \"issue\";\n  userName?: string;\n}\n\nexport interface GithubBotConfig {\n  appId: string;\n  /** PEM-encoded GitHub App private key. */\n  privateKey: string;\n  installationId: string;\n  /** `owner/repo` entries to watch; empty = all installation repositories. */\n  repos: string[];\n  pollIntervalMs: number;\n  workspace: Workspace;\n  /**\n   * Where the poll watermark state (baseline + seen ids) is persisted. Lives\n   * under the host-only state dir: the workspace dir can be mounted into\n   * sandboxes, and sandboxed code must not be able to clear dedup state and\n   * re-trigger runs.\n   */\n  syncStatePath: string;\n}\n\n/** Persisted per-repo poll watermark (DESIGN.md § Event source). */\ninterface GithubRepoSyncState {\n  /** Comments/issues created before this ISO instant never trigger. */\n  baseline: string;\n  /** Newest updated_at seen; polls fetch from (cursor - overlap). */\n  cursor: string;\n  seenComments: number[];\n  seenIssues: number[];\n  /** Optional so state files written before review-comment polling still load. */\n  seenReviewComments?: number[];\n}\n\nexport interface GithubSyncState {\n  repos: Record<string, GithubRepoSyncState>;\n}\n\nexport interface GithubRepoRef {\n  owner: string;\n  repo: string;\n}\n\nexport interface GithubConversationRef extends GithubRepoRef {\n  number: number;\n}\n\n// ── GitHub REST payload shapes (only the fields mikan reads) ─────────────────\n\ninterface GithubUser {\n  login: string;\n  type: string;\n}\n\nexport interface GithubIssue {\n  id: number;\n  number: number;\n  title: string;\n  body: string | null;\n  user: GithubUser;\n  created_at: string;\n  updated_at: string;\n  pull_request?: object;\n  /** open | closed */\n  state?: string;\n  labels?: { name: string }[];\n  assignees?: { login: string }[];\n}\n\nexport interface GithubIssueComment {\n  id: number;\n  body: string;\n  user: GithubUser;\n  created_at: string;\n  updated_at: string;\n  /** API URL of the parent issue, e.g. …/repos/o/r/issues/42 */\n  issue_url: string;\n}\n\n/** An inline PR review comment (a comment on a diff line). */\nexport interface GithubReviewComment {\n  id: number;\n  body: string;\n  user: GithubUser;\n  created_at: string;\n  updated_at: string;\n  /** API URL of the parent PR, e.g. …/repos/o/r/pulls/42 */\n  pull_request_url: string;\n  /** File the comment is anchored to. */\n  path: string;\n  /** Line in the diff's right side; null when the anchor is outdated. */\n  line: number | null;\n  /** The diff excerpt the comment is anchored to. */\n  diff_hunk: string;\n  /** Set on replies: the id of the thread's root comment. */\n  in_reply_to_id?: number;\n}\n\nexport interface GithubRepository {\n  name: string;\n  owner: GithubUser;\n}\n\nexport interface GithubRepositoryDetails {\n  default_branch: string;\n}\n\nexport interface GithubCollaboratorPermission {\n  /** Legacy field: admin | write | read | none (maintain→write, triage→read). */\n  permission: string;\n  /** Granular assigned role (admin/maintain/write/triage/read or a custom role). */\n  role_name?: string;\n}\n\nexport interface GithubPullRequest {\n  number: number;\n  html_url: string;\n  /** head.repo is null when the fork a PR came from was deleted. */\n  head?: { ref: string; sha: string; repo?: { full_name?: string } | null };\n  base?: { ref: string };\n  title?: string;\n  body?: string | null;\n  /** open | closed */\n  state?: string;\n  draft?: boolean;\n  merged?: boolean;\n  mergeable_state?: string;\n  changed_files?: number;\n  additions?: number;\n  deletions?: number;\n  user?: GithubUser;\n}\n\n/** One row of GET /pulls/{n}/files. */\nexport interface GithubPullRequestFile {\n  filename: string;\n  /** added | removed | modified | renamed | … */\n  status: string;\n  additions: number;\n  deletions: number;\n}\n\n/** One submitted review of GET /pulls/{n}/reviews. */\nexport interface GithubPullRequestReview {\n  id: number;\n  user: GithubUser;\n  body: string | null;\n  /** APPROVED | CHANGES_REQUESTED | COMMENTED | DISMISSED | PENDING */\n  state: string;\n  submitted_at?: string;\n}\n\nexport interface GithubCheckRun {\n  /** Check-run id; for GitHub Actions this doubles as the job id (log fetch). */\n  id: number;\n  name: string;\n  /** queued | in_progress | completed */\n  status: string;\n  /** success | failure | neutral | cancelled | skipped | timed_out | action_required | null while running */\n  conclusion: string | null;\n  html_url: string | null;\n  /** The app that reported the check (github-actions vs external CI). */\n  app?: { slug?: string } | null;\n  /** Whatever the reporting app posted about the run. */\n  output?: { title?: string | null; summary?: string | null } | null;\n}\n\n/** Permission subset requestable on a scoped installation token. */\nexport type GithubTokenPermissions = Partial<\n  Record<\"contents\" | \"pull_requests\" | \"issues\", \"read\" | \"write\">\n>;\n\nexport type GithubReactionContent =\n  | \"+1\"\n  | \"-1\"\n  | \"laugh\"\n  | \"confused\"\n  | \"heart\"\n  | \"hooray\"\n  | \"rocket\"\n  | \"eyes\";\n\nexport interface CloneRepoOptions {\n  /** HTTPS remote, e.g. https://github.com/owner/repo.git (no credentials). */\n  url: string;\n  /** Destination directory (the conversation dir's `repo/`). */\n  dir: string;\n  /** Ephemeral scoped installation token; used per-invocation, never stored. */\n  token: string;\n  botLogin: string;\n  botEmail: string;\n  /** When the conversation is a PR: fetch and check out its head. */\n  prNumber?: number;\n  /**\n   * The PR's head branch name when it lives in this repo (not a fork): the\n   * checkout is named after it so committing there + github_pr updates the\n   * PR in place. Absent (fork/unknown), the checkout falls back to pr-<n>.\n   */\n  prHeadBranch?: string;\n}\n\nexport interface PushBranchOptions {\n  dir: string;\n  branch: string;\n  token: string;\n}\n\nexport interface SyncRepoOptions {\n  dir: string;\n  /** Ephemeral contents:read token; used per-invocation, never stored. */\n  token: string;\n  /** Explicit branch to fetch; wins over prNumber/defaultBranch. */\n  branch?: string;\n  /** PR conversations: fetch pull/<n>/head into the local PR checkout. */\n  prNumber?: number;\n  /** Same-repo PR head name; the local checkout target. Fallback: pr-<n>. */\n  prHeadBranch?: string;\n  /** Fallback target when neither branch nor prNumber applies. */\n  defaultBranch?: string;\n}\n\nexport interface SyncRepoResult {\n  /** Local branch the fetch targets (the PR head name, pr-<n>, or the branch). */\n  target: string;\n  fetchedSha: string;\n  /** True when the checkout was moved to the fetched head. */\n  updatedCheckout: boolean;\n  /** Working tree had uncommitted changes (checkout left alone). */\n  dirty: boolean;\n  currentBranch: string;\n  /** Bot-committed (agent-made) commits on the target that origin lacks. */\n  localCommits: number;\n}\n\nexport interface GithubClientOptions {\n  appId: string;\n  privateKey: string;\n  installationId: string;\n  /** Override the API root for tests; defaults to https://api.github.com */\n  baseUrl?: string;\n  fetchImpl?: typeof fetch;\n}\n\n// ── Host-side tool contracts (capability pack, not messaging core) ───────────\n\n/** Arguments for the host-side `github_pr` tool. */\nexport interface GithubPrRequest {\n  /** Local branch in the conversation's ./repo clone; must match pi/<name>. */\n  branch: string;\n  title: string;\n  body?: string;\n  /** Target branch; defaults to the repository's default branch. */\n  base?: string;\n  draft?: boolean;\n}\n\nexport interface GithubPrResult {\n  number: number;\n  url: string;\n  /** True when the branch already had an open PR that this push updated. */\n  updatedExisting?: boolean;\n}\n\n/** Normalized check-run row for the host-side `github_checks` tool. */\nexport interface GithubCheckSummary {\n  /** Check-run id; for GitHub Actions checks it is also the job id for log fetch. */\n  id: number;\n  name: string;\n  /** queued | in_progress | completed */\n  status: string;\n  /** success | failure | … ; null while the run is still in progress */\n  conclusion: string | null;\n  url: string | null;\n  /** Slug of the reporting app; \"github-actions\" checks have fetchable logs. */\n  appSlug: string | null;\n  /** The reporting app's own summary of the run, when it posted one. */\n  outputSummary: string | null;\n}\n\nexport interface GithubChecksFns {\n  getChecks: (branch?: string) => Promise<GithubCheckSummary[]>;\n  getJobLog: (jobId: number) => Promise<string>;\n}\n\n/** Arguments for the host-side `github_read` tool. */\nexport interface GithubReadRequest {\n  action: \"pr\" | \"pr_files\" | \"pr_reviews\" | \"issue\" | \"comments\" | \"list\";\n  /** Issue/PR number; defaults to the conversation's own. */\n  number?: number;\n  /** list only: open | closed | all (default open). */\n  state?: string;\n  /** list only: comma-separated label names. */\n  labels?: string;\n  /** list only: filter by author login. */\n  creator?: string;\n}\n\n/** Typed payload of one `github_read` action; the tool renders it. */\nexport type GithubReadResult =\n  | { kind: \"pr\"; pr: GithubPullRequest }\n  | { kind: \"pr_files\"; files: GithubPullRequestFile[] }\n  | { kind: \"pr_reviews\"; reviews: GithubPullRequestReview[]; threads: GithubReviewComment[] }\n  | { kind: \"issue\"; issue: GithubIssue }\n  | { kind: \"comments\"; comments: GithubIssueComment[] }\n  | { kind: \"list\"; issues: GithubIssue[] };\n\n/** Arguments for the host-side `github_issue` tool. Deliberately a closed\n *  action set: lock/delete/transfer are not offered at all. */\nexport interface GithubIssueRequest {\n  action: \"add_labels\" | \"remove_label\" | \"add_assignees\" | \"remove_assignees\" | \"close\" | \"reopen\";\n  /** Issue/PR number; defaults to the conversation's own (triage may target others). */\n  number?: number;\n  /** add_labels */\n  labels?: string[];\n  /** remove_label */\n  label?: string;\n  /** add_assignees / remove_assignees */\n  assignees?: string[];\n  /** close */\n  state_reason?: \"completed\" | \"not_planned\";\n}\n\n/**\n * Host-side GitHub operations for github_* tools. Wired in main.ts over the\n * GitHub bot; tokens stay host-side. Consumed by `createGithubToolPack`.\n */\nexport type GithubSyncFn = (branch?: string) => Promise<string>;\n\nexport type GithubReviewReplyFn = (commentId: number, body: string) => Promise<{ url: string }>;\n\nexport type GithubReadFn = (request: GithubReadRequest) => Promise<GithubReadResult>;\n\nexport type GithubIssueFn = (request: GithubIssueRequest) => Promise<string>;\n\nexport interface PlatformGithubOps {\n  /** Push a prepared pi/* branch and open (or update) a pull request. */\n  pushAndCreatePr(conversationId: string, request: GithubPrRequest): Promise<GithubPrResult>;\n  /** CI check runs for a branch, or for the conversation's PR head when omitted. */\n  getChecks(conversationId: string, branch?: string): Promise<GithubCheckSummary[]>;\n  /** Log text of one CI job (an Actions check-run id), tail-truncated. */\n  getJobLog(conversationId: string, jobId: number): Promise<string>;\n  /** Reply inside one inline review thread of the conversation's PR. */\n  replyToReviewThread(\n    conversationId: string,\n    commentId: number,\n    body: string,\n  ): Promise<{ url: string }>;\n  /** Refresh the conversation's ./repo clone; returns a human-readable report. */\n  syncRepo(conversationId: string, branch?: string): Promise<string>;\n  /** Read PR/issue metadata the clone cannot provide; same repo only. */\n  readGithub(conversationId: string, request: GithubReadRequest): Promise<GithubReadResult>;\n  /** Label/assignee/state management on this repo's issues; returns a report. */\n  manageIssue(conversationId: string, request: GithubIssueRequest): Promise<string>;\n}\n\nexport interface GithubWebhookOptions {\n  secret: string;\n  /** Called after signature verification for relevant events. */\n  onPoke: () => void;\n}\n"]}

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

@@ -0,0 +1,20 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { GithubWebhookOptions } from "./types.js";
+export type { GithubWebhookOptions } from "./types.js";
+/**
+ * GitHub webhook receiver — a poke, not an event source. Deliveries are
+ * unordered, unguaranteed, and may repeat, so the payload is never parsed into
+ * the intake pipeline; a verified delivery only asks the bot to poll soon, and
+ * the poll's watermark/dedup discipline decides what actually triggers
+ * (DESIGN.md § Event source). Polling stays on as the missed-delivery
+ * backstop.
+ */
+export declare const GITHUB_WEBHOOK_PATH = "/github/webhook";
+/** Constant-time check of `X-Hub-Signature-256: sha256=<hex>` over the raw body. */
+export declare function verifyWebhookSignature(secret: string, body: Buffer, signatureHeader: string | undefined): boolean;
+/**
+ * Handle a request if it targets the webhook path. Returns false when the
+ * request is not for this route so the caller falls through.
+ */
+export declare function handleGithubWebhookRequest(req: IncomingMessage, res: ServerResponse, url: URL, options: GithubWebhookOptions): Promise<boolean>;
+//# sourceMappingURL=webhook.d.ts.map

package/dist/adapters/github/webhook.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.d.ts","sourceRoot":"","sources":["../../../src/adapters/github/webhook.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,WAAW,CAAC;AAEjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD,YAAY,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;;GAOG;AAEH,eAAO,MAAM,mBAAmB,oBAAoB,CAAC;AA0BrD,oFAAoF;AACpF,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,eAAe,EAAE,MAAM,GAAG,SAAS,GAClC,OAAO,CAMT;AAED;;;GAGG;AACH,wBAAsB,0BAA0B,CAC9C,GAAG,EAAE,eAAe,EACpB,GAAG,EAAE,cAAc,EACnB,GAAG,EAAE,GAAG,EACR,OAAO,EAAE,oBAAoB,GAC5B,OAAO,CAAC,OAAO,CAAC,CAoClB"}

package/dist/adapters/github/webhook.js

@@ -0,0 +1,78 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import * as log from "../../log.js";
+/**
+ * GitHub webhook receiver — a poke, not an event source. Deliveries are
+ * unordered, unguaranteed, and may repeat, so the payload is never parsed into
+ * the intake pipeline; a verified delivery only asks the bot to poll soon, and
+ * the poll's watermark/dedup discipline decides what actually triggers
+ * (DESIGN.md § Event source). Polling stays on as the missed-delivery
+ * backstop.
+ */
+export const GITHUB_WEBHOOK_PATH = "/github/webhook";
+/** Events that can carry a new conversation-triggering item. */
+const POKE_EVENTS = new Set(["issues", "issue_comment", "pull_request_review_comment"]);
+/** GitHub payloads are small; anything larger than this is not GitHub. */
+const MAX_BODY_BYTES = 1024 * 1024;
+function readBody(req, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        let size = 0;
+        req.on("data", (chunk) => {
+            size += chunk.length;
+            if (size > maxBytes) {
+                resolve(null);
+                req.destroy();
+                return;
+            }
+            chunks.push(chunk);
+        });
+        req.on("end", () => resolve(Buffer.concat(chunks)));
+        req.on("error", reject);
+    });
+}
+/** Constant-time check of `X-Hub-Signature-256: sha256=<hex>` over the raw body. */
+export function verifyWebhookSignature(secret, body, signatureHeader) {
+    if (!signatureHeader?.startsWith("sha256="))
+        return false;
+    const expected = createHmac("sha256", secret).update(body).digest("hex");
+    const received = signatureHeader.slice("sha256=".length);
+    if (received.length !== expected.length)
+        return false;
+    return timingSafeEqual(Buffer.from(received, "utf-8"), Buffer.from(expected, "utf-8"));
+}
+/**
+ * Handle a request if it targets the webhook path. Returns false when the
+ * request is not for this route so the caller falls through.
+ */
+export async function handleGithubWebhookRequest(req, res, url, options) {
+    if (url.pathname !== GITHUB_WEBHOOK_PATH)
+        return false;
+    if (req.method !== "POST") {
+        res.writeHead(405).end();
+        return true;
+    }
+    const body = await readBody(req, MAX_BODY_BYTES);
+    if (body === null) {
+        res.writeHead(413).end();
+        return true;
+    }
+    const signature = req.headers["x-hub-signature-256"];
+    if (!verifyWebhookSignature(options.secret, body, typeof signature === "string" ? signature : undefined)) {
+        log.logWarning("GitHub webhook: rejected delivery with bad or missing signature");
+        res.writeHead(401).end();
+        return true;
+    }
+    const event = req.headers["x-github-event"];
+    if (event === "ping") {
+        res.writeHead(200, { "Content-Type": "application/json" });
+        res.end(JSON.stringify({ ok: true }));
+        return true;
+    }
+    // Respond before the poll runs — GitHub times deliveries out at 10s.
+    res.writeHead(202).end();
+    if (typeof event === "string" && POKE_EVENTS.has(event)) {
+        options.onPoke();
+    }
+    return true;
+}
+//# sourceMappingURL=webhook.js.map

package/dist/adapters/github/webhook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"webhook.js","sourceRoot":"","sources":["../../../src/adapters/github/webhook.ts"],"names":[],"mappings":"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","sourcesContent":["import { createHmac, timingSafeEqual } from \"node:crypto\";\nimport type { IncomingMessage, ServerResponse } from \"node:http\";\nimport * as log from \"../../log.js\";\nimport type { GithubWebhookOptions } from \"./types.js\";\n\nexport type { GithubWebhookOptions } from \"./types.js\";\n\n/**\n * GitHub webhook receiver — a poke, not an event source. Deliveries are\n * unordered, unguaranteed, and may repeat, so the payload is never parsed into\n * the intake pipeline; a verified delivery only asks the bot to poll soon, and\n * the poll's watermark/dedup discipline decides what actually triggers\n * (DESIGN.md § Event source). Polling stays on as the missed-delivery\n * backstop.\n */\n\nexport const GITHUB_WEBHOOK_PATH = \"/github/webhook\";\n\n/** Events that can carry a new conversation-triggering item. */\nconst POKE_EVENTS = new Set([\"issues\", \"issue_comment\", \"pull_request_review_comment\"]);\n\n/** GitHub payloads are small; anything larger than this is not GitHub. */\nconst MAX_BODY_BYTES = 1024 * 1024;\n\nfunction readBody(req: IncomingMessage, maxBytes: number): Promise<Buffer | null> {\n  return new Promise((resolve, reject) => {\n    const chunks: Buffer[] = [];\n    let size = 0;\n    req.on(\"data\", (chunk: Buffer) => {\n      size += chunk.length;\n      if (size > maxBytes) {\n        resolve(null);\n        req.destroy();\n        return;\n      }\n      chunks.push(chunk);\n    });\n    req.on(\"end\", () => resolve(Buffer.concat(chunks)));\n    req.on(\"error\", reject);\n  });\n}\n\n/** Constant-time check of `X-Hub-Signature-256: sha256=<hex>` over the raw body. */\nexport function verifyWebhookSignature(\n  secret: string,\n  body: Buffer,\n  signatureHeader: string | undefined,\n): boolean {\n  if (!signatureHeader?.startsWith(\"sha256=\")) return false;\n  const expected = createHmac(\"sha256\", secret).update(body).digest(\"hex\");\n  const received = signatureHeader.slice(\"sha256=\".length);\n  if (received.length !== expected.length) return false;\n  return timingSafeEqual(Buffer.from(received, \"utf-8\"), Buffer.from(expected, \"utf-8\"));\n}\n\n/**\n * Handle a request if it targets the webhook path. Returns false when the\n * request is not for this route so the caller falls through.\n */\nexport async function handleGithubWebhookRequest(\n  req: IncomingMessage,\n  res: ServerResponse,\n  url: URL,\n  options: GithubWebhookOptions,\n): Promise<boolean> {\n  if (url.pathname !== GITHUB_WEBHOOK_PATH) return false;\n  if (req.method !== \"POST\") {\n    res.writeHead(405).end();\n    return true;\n  }\n  const body = await readBody(req, MAX_BODY_BYTES);\n  if (body === null) {\n    res.writeHead(413).end();\n    return true;\n  }\n  const signature = req.headers[\"x-hub-signature-256\"];\n  if (\n    !verifyWebhookSignature(\n      options.secret,\n      body,\n      typeof signature === \"string\" ? signature : undefined,\n    )\n  ) {\n    log.logWarning(\"GitHub webhook: rejected delivery with bad or missing signature\");\n    res.writeHead(401).end();\n    return true;\n  }\n\n  const event = req.headers[\"x-github-event\"];\n  if (event === \"ping\") {\n    res.writeHead(200, { \"Content-Type\": \"application/json\" });\n    res.end(JSON.stringify({ ok: true }));\n    return true;\n  }\n  // Respond before the poll runs — GitHub times deliveries out at 10s.\n  res.writeHead(202).end();\n  if (typeof event === \"string\" && POKE_EVENTS.has(event)) {\n    options.onPoke();\n  }\n  return true;\n}\n"]}

package/dist/adapters/index.d.ts

@@ -0,0 +1,12 @@
+import type { ConversationEvent, ConversationMessage, OfficeAddress, PlatformName } from "../types.js";
+export type { MessagingBot, ConversationContext, ConversationEvent, MessagingEventHandler, HandleNewCommandOptions, ConversationMessage, ConversationResponder, ChatToolResult, ConversationKind, MessagingInfo, OfficeAddress, OfficeKey, PlatformHistoryMessage, PlatformHistoryOptions, PlatformName, PlatformUserInfo, RunningSession, SubagentProgressSnapshot, } from "../types.js";
+interface ConversationIdentityInput {
+    platform: PlatformName;
+    conversationId: string;
+    address?: OfficeAddress;
+}
+/** Normalize platform intake into one authoritative conversation identity. */
+export declare function createConversationEvent<T extends Omit<ConversationEvent, "address" | "conversationId">>(input: T & ConversationIdentityInput): T & ConversationEvent;
+/** Normalize a platform response context into one authoritative identity. */
+export declare function createConversationMessage<T extends Omit<ConversationMessage, "address" | "conversationId">>(input: T & ConversationIdentityInput): T & ConversationMessage;
+//# sourceMappingURL=index.d.ts.map

package/dist/adapters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,aAAa,EACb,YAAY,EACb,MAAM,aAAa,CAAC;AAErB,YAAY,EACV,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,qBAAqB,EACrB,uBAAuB,EACvB,mBAAmB,EACnB,qBAAqB,EACrB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,EACb,SAAS,EACT,sBAAsB,EACtB,sBAAsB,EACtB,YAAY,EACZ,gBAAgB,EAChB,cAAc,EACd,wBAAwB,GACzB,MAAM,aAAa,CAAC;AAErB,UAAU,yBAAyB;IACjC,QAAQ,EAAE,YAAY,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,CAAC,EAAE,aAAa,CAAC;CACzB;AAYD,8EAA8E;AAC9E,wBAAgB,uBAAuB,CACrC,CAAC,SAAS,IAAI,CAAC,iBAAiB,EAAE,SAAS,GAAG,gBAAgB,CAAC,EAC/D,KAAK,EAAE,CAAC,GAAG,yBAAyB,GAAG,CAAC,GAAG,iBAAiB,CAG7D;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CACvC,CAAC,SAAS,IAAI,CAAC,mBAAmB,EAAE,SAAS,GAAG,gBAAgB,CAAC,EACjE,KAAK,EAAE,CAAC,GAAG,yBAAyB,GAAG,CAAC,GAAG,mBAAmB,CAG/D"}

package/dist/adapters/index.js

@@ -0,0 +1,19 @@
+import { createOfficeAddress, sameOffice } from "../office/index.js";
+function resolveConversationAddress(input) {
+    const address = createOfficeAddress(input.platform, input.conversationId);
+    if (input.address && !sameOffice(address, input.address)) {
+        throw new Error(`Conversation address mismatch for ${JSON.stringify(input.conversationId)} on ${input.platform}`);
+    }
+    return address;
+}
+/** Normalize platform intake into one authoritative conversation identity. */
+export function createConversationEvent(input) {
+    const address = resolveConversationAddress(input);
+    return { ...input, address, conversationId: address.conversationId };
+}
+/** Normalize a platform response context into one authoritative identity. */
+export function createConversationMessage(input) {
+    const address = resolveConversationAddress(input);
+    return { ...input, address, conversationId: address.conversationId };
+}
+//# sourceMappingURL=index.js.map

package/dist/adapters/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/adapters/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAmCrE,SAAS,0BAA0B,CAAC,KAAgC;IAClE,MAAM,OAAO,GAAG,mBAAmB,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,cAAc,CAAC,CAAC;IAC1E,IAAI,KAAK,CAAC,OAAO,IAAI,CAAC,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC;QACzD,MAAM,IAAI,KAAK,CACb,qCAAqC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,cAAc,CAAC,OAAO,KAAK,CAAC,QAAQ,EAAE,CACjG,CAAC;IACJ,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,uBAAuB,CAErC,KAAoC;IACpC,MAAM,OAAO,GAAG,0BAA0B,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;AACvE,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,yBAAyB,CAEvC,KAAoC;IACpC,MAAM,OAAO,GAAG,0BAA0B,CAAC,KAAK,CAAC,CAAC;IAClD,OAAO,EAAE,GAAG,KAAK,EAAE,OAAO,EAAE,cAAc,EAAE,OAAO,CAAC,cAAc,EAAE,CAAC;AACvE,CAAC","sourcesContent":["import { createOfficeAddress, sameOffice } from \"../office/index.js\";\nimport type {\n  ConversationEvent,\n  ConversationMessage,\n  OfficeAddress,\n  PlatformName,\n} from \"../types.js\";\n\nexport type {\n  MessagingBot,\n  ConversationContext,\n  ConversationEvent,\n  MessagingEventHandler,\n  HandleNewCommandOptions,\n  ConversationMessage,\n  ConversationResponder,\n  ChatToolResult,\n  ConversationKind,\n  MessagingInfo,\n  OfficeAddress,\n  OfficeKey,\n  PlatformHistoryMessage,\n  PlatformHistoryOptions,\n  PlatformName,\n  PlatformUserInfo,\n  RunningSession,\n  SubagentProgressSnapshot,\n} from \"../types.js\";\n\ninterface ConversationIdentityInput {\n  platform: PlatformName;\n  conversationId: string;\n  address?: OfficeAddress;\n}\n\nfunction resolveConversationAddress(input: ConversationIdentityInput): OfficeAddress {\n  const address = createOfficeAddress(input.platform, input.conversationId);\n  if (input.address && !sameOffice(address, input.address)) {\n    throw new Error(\n      `Conversation address mismatch for ${JSON.stringify(input.conversationId)} on ${input.platform}`,\n    );\n  }\n  return address;\n}\n\n/** Normalize platform intake into one authoritative conversation identity. */\nexport function createConversationEvent<\n  T extends Omit<ConversationEvent, \"address\" | \"conversationId\">,\n>(input: T & ConversationIdentityInput): T & ConversationEvent {\n  const address = resolveConversationAddress(input);\n  return { ...input, address, conversationId: address.conversationId };\n}\n\n/** Normalize a platform response context into one authoritative identity. */\nexport function createConversationMessage<\n  T extends Omit<ConversationMessage, \"address\" | \"conversationId\">,\n>(input: T & ConversationIdentityInput): T & ConversationMessage {\n  const address = resolveConversationAddress(input);\n  return { ...input, address, conversationId: address.conversationId };\n}\n"]}

package/dist/adapters/intake.d.ts

@@ -1,11 +1,22 @@
-import type { ConversationEvent } from "../adapter.js";
-import type { MessageIntakeOptions } from "./types.js";
+import type { ConversationEvent } from "./index.js";
+import type { MessageIntakeOptions, MessageIntakeOutcome } from "./types.js";
+/**
+ * Recognize a magic word: a highest-priority chat control phrase that bypasses
+ * trigger policy and queueing (see CONTEXT.md). One grammar for every
+ * platform: optional leading slash, optional `@botname` suffix, any case.
+ */
+export declare function matchMagicWord(text: string): "stop" | null;
 /**
  * Shared message ingress pipeline for platform adapters.
  *
- * Platform adapters still normalize SDK events and handle platform-specific stop
- * semantics. This module owns the common trigger/log/attachment/queue/handler
- * ordering for messages that may start an agent run.
+ * Platform adapters normalize SDK events; this module owns the ordering for
+ * messages that may start an agent run:
+ *
+ *   magic word → trigger policy → attachments → log → busy policy → queue → dispatch
+ *
+ * Magic words are matched before the trigger gate — `stop` must never wait on
+ * trigger filtering or queue behind a running agent turn. Adapters state
+ * platform policy as data (`magicWord`, `busyPolicy`) instead of callbacks.
  */
-export declare function processMessageIntake<TEvent extends ConversationEvent>(options: MessageIntakeOptions<TEvent>): Promise<void>;
+export declare function processMessageIntake<TEvent extends ConversationEvent>(options: MessageIntakeOptions<TEvent>): Promise<MessageIntakeOutcome>;
 //# sourceMappingURL=intake.d.ts.map

package/dist/adapters/intake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intake.d.ts","sourceRoot":"","sources":["../../src/adapters/intake.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAEvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEvD;;;;;;GAMG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,SAAS,iBAAiB,EACzE,OAAO,EAAE,oBAAoB,CAAC,MAAM,CAAC,GACpC,OAAO,CAAC,IAAI,CAAC,CAqCf"}
+{"version":3,"file":"intake.d.ts","sourceRoot":"","sources":["../../src/adapters/intake.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAGpD,OAAO,KAAK,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAE7E;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAE1D;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CAAC,MAAM,SAAS,iBAAiB,EACzE,OAAO,EAAE,oBAAoB,CAAC,MAAM,CAAC,GACpC,OAAO,CAAC,oBAAoB,CAAC,CAuD/B"}