@github-tools/eve-extension 0.11.0 → 0.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -9,7 +9,7 @@
9
9
 
10
10
  GitHub tools for [eve](https://eve.dev), packaged as a mountable [eve extension](https://eve.dev/docs/extensions): a single `pnpm add` and a one-line mount, with no CLI setup. Built on [`@github-tools/sdk/eve-runtime`](../github-tools) (shared descriptors, execution, and approval helpers).
11
11
 
12
- Docs: **[github-tools.com/frameworks/eve-extension](https://github-tools.com/frameworks/eve-extension)**
12
+ Docs: **[github-tools.com/integrations/eve](https://github-tools.com/integrations/eve)**
13
13
 
14
14
  This is **the recommended way** to add GitHub tools to an eve agent. The legacy [`createGithubTools`](../github-tools) / per-tool factories from `@github-tools/sdk/eve` (direct `agent/tools/` registration) are **deprecated** in its favor. They keep working for existing agents, but new agents should mount this extension instead.
15
15
 
@@ -81,6 +81,25 @@ export default githubExtension({
81
81
 
82
82
  See the runnable consumer at [`examples/eve`](../../examples/eve).
83
83
 
84
+ ## Choose who the agent answers on GitHub
85
+
86
+ On [eve's GitHub channel](https://eve.dev/docs/channels/github), anyone who mentions the bot starts a turn, including on a public repository. `@github-tools/eve-extension/channels` exports eve's `githubChannel` with one more option, `respondTo`:
87
+
88
+ ```ts
89
+ // agent/channels/github.ts
90
+ import { connectGitHubCredentials } from '@vercel/connect/eve'
91
+ import { githubChannel } from '@github-tools/eve-extension/channels'
92
+
93
+ export default githubChannel({
94
+ credentials: connectGitHubCredentials('github/my-connector'),
95
+ respondTo: 'writers',
96
+ })
97
+ ```
98
+
99
+ `respondTo` takes `'anyone'` (default), `'triagers'`, `'writers'`, `'maintainers'` or `'admins'`: GitHub's repository roles, each meaning that role and everyone above it. The channel reads the commenter's role on the thread's repository before a comment starts or continues a turn, so a comment from anyone below it leaves no reaction, no session and no model call. Every other option is eve's.
100
+
101
+ Pair it with `actAs: 'caller'`, which limits what a turn does to the commenter's role on each repository a call targets.
102
+
84
103
  ## Structure
85
104
 
86
105
  ```
@@ -88,6 +107,8 @@ extension/
88
107
  extension.ts # defineExtension() config schema (token, connector, preset, include, exclude, requireApproval, ...)
89
108
  tools/
90
109
  github.ts # defineDynamic() resolving listEveToolDescriptors(...) into authored defineTool calls
110
+ channels/
111
+ index.ts # githubChannel with respondTo, compiled apart from the extension to channels/dist
91
112
  ```
92
113
 
93
114
  ## Config schema (`extension/extension.ts`)
@@ -96,7 +117,7 @@ extension/
96
117
  |---|---|---|
97
118
  | `token` | `string \| (() => Promise<string>)` (optional) | PAT string, or an async provider for rotating tokens (e.g. a GitHub App installation token) — the same `GithubTokenInput` the SDK accepts; falls back to `GITHUB_TOKEN` when omitted and `connector` is not set |
98
119
  | `connector` | `string \| (() => string \| Promise<string>)` (optional) | Vercel Connect connector name, or a resolver to pick one dynamically (e.g. per environment/tenant); takes priority over `token` |
99
- | `actAs` | `'app' \| 'user' \| 'caller' \| { read, write }` (optional) | Whose GitHub access the tools use when `connector` is set. `'app'` (default) uses the GitHub App installation. `'user'` runs each call with the signed-in eve user's own GitHub token, so the agent can do what that user can do on GitHub and nothing more; sessions without a signed-in user fail. `'caller'` uses the user when one drives the turn and the App otherwise (schedules, bots). Users who have not authorized the App get a sign-in prompt and never fall back to the App. `{ read, write }` picks per tool kind, `overrides.<tool>.actAs` per tool. The default may change to `'caller'` in a future major version |
120
+ | `actAs` | `'app' \| 'user' \| 'caller' \| { read, write }` (optional) | Whose GitHub access the tools use when `connector` is set. `'app'` (default) uses the GitHub App installation. `'user'` runs each call with the signed-in eve user's own GitHub token, so the agent can do what that user can do on GitHub and nothing more; sessions without a signed-in user fail. `'caller'` uses the user when one drives the turn and the App otherwise (schedules, bots). Users who have not authorized the App get a sign-in prompt and never fall back to the App. Someone who comments on eve's GitHub channel can't sign in, so their call runs as the App once their own role on the target repository allows it (Read for a read, Write for a write), and fails with `CALLER_FORBIDDEN` otherwise. `{ read, write }` picks per tool kind, `overrides.<tool>.actAs` per tool. The default may change to `'caller'` in a future major version |
100
121
  | `approvers` | `'requester' \| 'anyone'` (optional) | Who may answer an approval. `'requester'` (default) is only the person who asked, so a colleague cannot approve your request. `'anyone'` is an opt-in that lets any signed-in user approve and anyone deny; for `'user'` and `'caller'` tools the approved call runs with the approver's GitHub token, after they sign in |
101
122
  | `connect` | `record \| ((ctx, call) => record)` (optional) | Passed through to `getToken` when `connector` is set. `connect.subject` defaults to `{ type: 'app' }` (the project's GitHub App installation); for per-user tokens, use `actAs`. App tokens target the installation owning each call's repository unless `installationId`, `authorizationDetails` or `repositories` pins one; pass a `(ctx, call) => record` resolver for other per-call rules |
102
123
  | `preset` | preset name, array, or `'auto'` | `code-review`, `issue-triage`, `ci-ops`, `repo-explorer`, `security-audit`, `release-manager`, `discussion-moderator`, `notification-inbox`, `pr-author`, `maintainer`; `'auto'` lists the tools the session's first request needs and defers the rest |
@@ -111,7 +132,7 @@ extension/
111
132
  ## Build (contributors)
112
133
 
113
134
  ```sh
114
- pnpm --filter @github-tools/eve-extension build # runs `eve extension build`
135
+ pnpm --filter @github-tools/eve-extension build # runs `eve extension build`, then compiles `channels/`
115
136
  ```
116
137
 
117
138
  ## License
@@ -0,0 +1,37 @@
1
+ import { type GitHubChannel, type GitHubChannelConfig } from 'eve/channels/github';
2
+ /**
3
+ * Who the agent answers on GitHub, named after GitHub's repository roles. Each value means the
4
+ * people with that role and everyone above them: `'writers'` is Write, Maintain and Admin.
5
+ */
6
+ export type GithubRespondTo = 'anyone' | 'triagers' | 'writers' | 'maintainers' | 'admins';
7
+ /** eve's `githubChannel` config, plus {@link GithubChannelConfig.respondTo}. */
8
+ export interface GithubChannelConfig extends GitHubChannelConfig {
9
+ /**
10
+ * Who may reach the agent with a comment. The commenter's role on the thread's repository is
11
+ * checked before the comment starts or continues a turn, so a comment from anyone below it does
12
+ * nothing: no reaction, no session, no model call.
13
+ *
14
+ * - `'anyone'` (default): anyone who can comment, which on a public repository is every GitHub user.
15
+ * - `'triagers'`, `'writers'`, `'maintainers'`, `'admins'`: that role and everyone above it.
16
+ *
17
+ * It applies to comments only: `onIssue`, `onPullRequest` and the CI hooks decide for themselves.
18
+ * With your own `onComment`, the role is checked for the comments it dispatches.
19
+ */
20
+ readonly respondTo?: GithubRespondTo;
21
+ }
22
+ /**
23
+ * eve's `githubChannel` with `respondTo`, which limits who can reach the agent with a comment to
24
+ * the people with a role on the repository. Every other option is eve's and passes through.
25
+ *
26
+ * ```ts
27
+ * // agent/channels/github.ts
28
+ * import { connectGitHubCredentials } from '@vercel/connect/eve'
29
+ * import { githubChannel } from '@github-tools/eve-extension/channels'
30
+ *
31
+ * export default githubChannel({
32
+ * credentials: connectGitHubCredentials('github/my-connector'),
33
+ * respondTo: 'writers',
34
+ * })
35
+ * ```
36
+ */
37
+ export declare function githubChannel({ respondTo, ...config }?: GithubChannelConfig): GitHubChannel;
@@ -0,0 +1,68 @@
1
+ import { GITHUB_ROLES, githubRoleRank } from '@github-tools/sdk/eve-runtime';
2
+ import { defaultGitHubAuth, GitHubApiError, githubChannel as eveGithubChannel, } from 'eve/channels/github';
3
+ const MINIMUM_ROLE = {
4
+ triagers: 'triage',
5
+ writers: 'write',
6
+ maintainers: 'maintain',
7
+ admins: 'admin',
8
+ };
9
+ async function resolveBotName(name) {
10
+ return (typeof name === 'function' ? await name() : name)?.trim() || undefined;
11
+ }
12
+ // Same rule as eve's default gate, which it doesn't export: skip eve's own comments and other
13
+ // bots, and need `@botName` followed by a character that can't continue a login.
14
+ function mentionsBot(comment, botName) {
15
+ if (!botName || comment.body.includes('<!-- eve:github:'))
16
+ return false;
17
+ if (comment.author?.type === 'Bot' || comment.author?.login.toLowerCase() === `${botName}[bot]`.toLowerCase())
18
+ return false;
19
+ return new RegExp(`@${botName.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')}(?=$|[^A-Za-z0-9_-])`, 'iu').test(comment.body);
20
+ }
21
+ async function commenterRank(ctx) {
22
+ try {
23
+ const { body } = await ctx.github.request({
24
+ method: 'GET',
25
+ path: `/repos/${ctx.repository.fullName}/collaborators/${encodeURIComponent(ctx.sender.login)}/permission`,
26
+ });
27
+ return githubRoleRank({ permission: body.permission, roleName: body.role_name });
28
+ }
29
+ catch (error) {
30
+ // GitHub answers 404 for a sender that is not a user account.
31
+ if (error instanceof GitHubApiError && error.status === 404)
32
+ return -1;
33
+ throw error;
34
+ }
35
+ }
36
+ /**
37
+ * eve's `githubChannel` with `respondTo`, which limits who can reach the agent with a comment to
38
+ * the people with a role on the repository. Every other option is eve's and passes through.
39
+ *
40
+ * ```ts
41
+ * // agent/channels/github.ts
42
+ * import { connectGitHubCredentials } from '@vercel/connect/eve'
43
+ * import { githubChannel } from '@github-tools/eve-extension/channels'
44
+ *
45
+ * export default githubChannel({
46
+ * credentials: connectGitHubCredentials('github/my-connector'),
47
+ * respondTo: 'writers',
48
+ * })
49
+ * ```
50
+ */
51
+ export function githubChannel({ respondTo = 'anyone', ...config } = {}) {
52
+ if (respondTo === 'anyone')
53
+ return eveGithubChannel(config);
54
+ const minimum = GITHUB_ROLES.indexOf(MINIMUM_ROLE[respondTo]);
55
+ const { onComment } = config;
56
+ const botName = config.botName ?? config.credentials?.appSlug ?? process.env.GITHUB_APP_SLUG;
57
+ return eveGithubChannel({
58
+ ...config,
59
+ async onComment(ctx, comment) {
60
+ const result = onComment
61
+ ? await onComment(ctx, comment)
62
+ : mentionsBot(comment, await resolveBotName(botName)) ? { auth: defaultGitHubAuth(ctx) } : null;
63
+ if (!result)
64
+ return null;
65
+ return await commenterRank(ctx) >= minimum ? result : null;
66
+ },
67
+ });
68
+ }
@@ -1,7 +1,7 @@
1
1
  import type { GithubTokenCall, GithubTokenInput } from '@github-tools/sdk';
2
2
  import type { ConnectTokenSubject, GithubConnectorInput, GithubConnectParams } from '@github-tools/sdk/connect';
3
3
  import type { ToolContext } from 'eve/tools';
4
- import { type CommitIdentity, type EveApprovalValue, type EveToolOverrides, type GithubEvaluationOptions, type GithubToolName, type GithubToolPreset, type GithubWriteToolName } from '@github-tools/sdk/eve-runtime';
4
+ import { type CommitIdentity, type EveApprovalValue, type EveToolOverrides, type GithubEvaluationOptions, type GithubGuardrails, type GithubToolName, type GithubToolPreset, type GithubWriteToolName } from '@github-tools/sdk/eve-runtime';
5
5
  import { z } from 'zod';
6
6
  /**
7
7
  * Default owner / repo / PR / issue / ref for tool inputs.
@@ -100,7 +100,10 @@ export interface GithubExtensionConfig {
100
100
  * - `'caller'`: `'user'` when a signed-in user drives the turn, the App when
101
101
  * nobody does (schedules, automations, bots). A user who has not
102
102
  * authorized the App is asked to sign in; the call never falls back to
103
- * the App for them.
103
+ * the App for them. Someone who comments on eve's GitHub channel can't
104
+ * sign in, so their call runs as the App once their own role on the
105
+ * repository it targets allows it: Read for a read, Write for a write.
106
+ * A refused call fails with `github_tools.CALLER_FORBIDDEN`.
104
107
  *
105
108
  * GitHub allows a user-token call only when both the user and the App have
106
109
  * access, so a maintainer can do what a maintainer can, and a reader can
@@ -175,6 +178,23 @@ export interface GithubExtensionConfig {
175
178
  committer?: CommitIdentity;
176
179
  /** Co-authors to attribute on commits created by tools. */
177
180
  coAuthors?: CommitIdentity[];
181
+ /**
182
+ * Repositories and branches the tools may act on, checked before each call reaches GitHub.
183
+ * `repositories` takes `owner/repo` or `owner/*`; `branches` takes names or patterns such as
184
+ * `agent/*` and covers commits, branch creation and deletion, merges into a pull request's base,
185
+ * and updates of a pull request's branch. A call whose input contains what looks like a
186
+ * credential is blocked too, unless `secrets: 'allow'`. A blocked write is denied with the reason
187
+ * instead of asking anyone to approve it.
188
+ */
189
+ guardrails?: GithubGuardrails;
190
+ /**
191
+ * Shadow mode: run reads as usual but send no write to GitHub, and ask nobody to approve one.
192
+ * Each write still goes through `guardrails`, then returns a dry-run result that says whether
193
+ * approval would have asked a person (with the evaluation model's verdict under `'auto'`), and
194
+ * its label reads "Would create issue on owner/repo". Use it to try the agent on real
195
+ * repositories, for example a scheduled bot, before letting it write.
196
+ */
197
+ dryRun?: boolean;
178
198
  }
179
199
  declare const _default: import("eve/extension").ExtensionHandle<z.ZodType<GithubExtensionConfig, GithubExtensionConfig, z.core.$ZodTypeInternals<GithubExtensionConfig, GithubExtensionConfig>>>;
180
200
  export default _default;
@@ -1 +1 @@
1
- {"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../extension/extension.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../extension/extension.ts"],"names":[],"mappings":"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"}
@@ -62,7 +62,13 @@ const configSchema = z.object({
62
62
  overrides: z.partialRecord(toolNameSchema, z.looseObject({ actAs: actAsSchema.optional() })).optional(),
63
63
  author: commitIdentitySchema.optional(),
64
64
  committer: commitIdentitySchema.optional(),
65
- coAuthors: z.array(commitIdentitySchema).optional()
65
+ coAuthors: z.array(commitIdentitySchema).optional(),
66
+ guardrails: z.object({
67
+ repositories: z.array(z.string()).optional(),
68
+ branches: z.array(z.string()).optional(),
69
+ secrets: z.enum(["block", "allow"]).optional()
70
+ }).optional(),
71
+ dryRun: z.boolean().optional()
66
72
  }).superRefine((config, ctx) => {
67
73
  const { actAs } = config;
68
74
  const identities = [...typeof actAs === "object" ? [actAs.read, actAs.write] : [actAs], ...Object.values(config.overrides ?? {}).map((override) => override?.actAs)];
@@ -1 +1 @@
1
- {"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../../extension/instructions.ts"],"names":[],"mappings":";AAMA,wBAQE"}
1
+ {"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../../extension/instructions.ts"],"names":[],"mappings":";AAOA,wBAQE"}
@@ -5,13 +5,14 @@ const __filename = __eveFileURLToPath(import.meta.url);
5
5
  __eveDirname(__filename);
6
6
  __eveCreateRequire(import.meta.url);
7
7
  import extension_default from "./extension.mjs";
8
+ import { sessionContext } from "./lib/context.mjs";
8
9
  import { resolveToolGuidance } from "@github-tools/sdk/eve-runtime";
9
10
  import { defineDynamic, defineInstructions } from "eve/instructions";
10
- var instructions_default = defineDynamic(() => {
11
- const { preset, context } = extension_default.config;
11
+ var instructions_default = defineDynamic((ctx) => {
12
+ const { preset } = extension_default.config;
12
13
  const guidance = resolveToolGuidance({
13
14
  preset: preset === "auto" ? void 0 : preset,
14
- context
15
+ context: sessionContext(ctx.session.auth.current)
15
16
  });
16
17
  return defineInstructions({ content: `GitHub tools: the tool names below leave out this extension's prefix, such as \`github__\`.${preset === "auto" ? " A GitHub tool that is not in your tool list can be found with `eve__search`." : ""}\n\n${guidance}` });
17
18
  });
@@ -0,0 +1,14 @@
1
+ import type { GithubCaller } from '@github-tools/sdk/eve-runtime';
2
+ type SessionAuth = {
3
+ readonly authenticator?: string;
4
+ readonly principalType?: string;
5
+ readonly attributes?: Readonly<Record<string, string | readonly string[]>>;
6
+ } | null | undefined;
7
+ /**
8
+ * The person behind a turn from eve's GitHub channel, or `undefined` for any other caller. GitHub
9
+ * vouches for who they are, but a public comment can't carry a sign-in, so they never get a token
10
+ * of their own.
11
+ */
12
+ export declare function githubCommenter(auth: SessionAuth): GithubCaller | undefined;
13
+ export {};
14
+ //# sourceMappingURL=commenter.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"commenter.d.ts","sourceRoot":"","sources":["../../../../extension/lib/commenter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAA;AAEjE,KAAK,WAAW,GAAG;IACjB,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;CAC3E,GAAG,IAAI,GAAG,SAAS,CAAA;AAEpB;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,WAAW,GAAG,YAAY,GAAG,SAAS,CAM3E"}
@@ -0,0 +1,20 @@
1
+ import { fileURLToPath as __eveFileURLToPath } from "node:url";
2
+ import { dirname as __eveDirname } from "node:path";
3
+ import { createRequire as __eveCreateRequire } from "node:module";
4
+ const __filename = __eveFileURLToPath(import.meta.url);
5
+ __eveDirname(__filename);
6
+ __eveCreateRequire(import.meta.url);
7
+ function githubCommenter(auth) {
8
+ if (auth?.authenticator !== "github-webhook" || auth.principalType !== "user") return void 0;
9
+ const { user_login: login, repository } = auth.attributes ?? {};
10
+ if (typeof login !== "string" || !login) return void 0;
11
+ const [owner, repo] = typeof repository === "string" ? repository.split("/") : [];
12
+ return {
13
+ login,
14
+ ...owner && repo && { repository: {
15
+ owner,
16
+ repo
17
+ } }
18
+ };
19
+ }
20
+ export { githubCommenter };
@@ -0,0 +1,12 @@
1
+ import { type GithubExtensionContext } from '../extension';
2
+ type SessionAuth = {
3
+ readonly authenticator?: string;
4
+ readonly attributes?: Readonly<Record<string, string | readonly string[]>>;
5
+ } | null | undefined;
6
+ /**
7
+ * The extension's `context`, with the fields it leaves out filled from the GitHub channel's thread:
8
+ * the repository, and the issue or pull request number. Other channels add nothing.
9
+ */
10
+ export declare function sessionContext(auth: SessionAuth): GithubExtensionContext | undefined;
11
+ export {};
12
+ //# sourceMappingURL=context.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../../extension/lib/context.ts"],"names":[],"mappings":"AAAA,OAAkB,EAAE,KAAK,sBAAsB,EAAE,MAAM,cAAc,CAAA;AAErE,KAAK,WAAW,GAAG;IAAE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC,CAAC,CAAA;CAAE,GAAG,IAAI,GAAG,SAAS,CAAA;AAErJ;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,WAAW,GAAG,sBAAsB,GAAG,SAAS,CAUpF"}
@@ -0,0 +1,24 @@
1
+ import { fileURLToPath as __eveFileURLToPath } from "node:url";
2
+ import { dirname as __eveDirname } from "node:path";
3
+ import { createRequire as __eveCreateRequire } from "node:module";
4
+ const __filename = __eveFileURLToPath(import.meta.url);
5
+ __eveDirname(__filename);
6
+ __eveCreateRequire(import.meta.url);
7
+ import extension_default from "../extension.mjs";
8
+ function sessionContext(auth) {
9
+ const configured = extension_default.config.context;
10
+ if (auth?.authenticator !== "github-webhook") return configured;
11
+ const { repository, issue_number: issue, pull_request_number: pull } = auth.attributes ?? {};
12
+ const [owner, repo] = typeof repository === "string" ? repository.split("/") : [];
13
+ if (!owner || !repo) return configured;
14
+ const pullNumber = Number(pull) || void 0;
15
+ const issueNumber = Number(issue) || pullNumber;
16
+ return {
17
+ owner,
18
+ repo,
19
+ ...pullNumber && { pullNumber },
20
+ ...issueNumber && { issueNumber },
21
+ ...configured
22
+ };
23
+ }
24
+ export { sessionContext };
@@ -1 +1 @@
1
- {"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../../extension/tools/github.ts"],"names":[],"mappings":";AAmVA,wBAqDE"}
1
+ {"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../../extension/tools/github.ts"],"names":[],"mappings":";AAmYA,wBAsDE"}
@@ -4,14 +4,17 @@ import { createRequire as __eveCreateRequire } from "node:module";
4
4
  const __filename = __eveFileURLToPath(import.meta.url);
5
5
  __eveDirname(__filename);
6
6
  __eveCreateRequire(import.meta.url);
7
+ import { githubCommenter } from "../lib/commenter.mjs";
8
+ import { sessionContext } from "../lib/context.mjs";
7
9
  import extension_default from "../extension.mjs";
8
- import { AUTO_APPROVAL_TOOLS, GITHUB_TOOL_NAMES, GITHUB_WRITE_TOOLS, autoApprovalDecision, evaluatePresets, evaluateTools, executeGithubEveTool, fallbackPresets, fallbackTools, formatGithubEveToolOutput, githubToolsErrors, isEveApprovalDisabled, latestUserText, listEveToolDescriptors, mapEveApprovalValue } from "@github-tools/sdk/eve-runtime";
10
+ import { AUTO_APPROVAL_TOOLS, GITHUB_TOOL_NAMES, GITHUB_WRITE_TOOLS, autoApprovalDecision, evaluatePresets, evaluateTools, executeGithubEveTool, fallbackPresets, fallbackTools, formatGithubEveToolOutput, githubGuardrailViolation, githubToolsErrors, isEveApprovalDisabled, latestUserText, listEveToolDescriptors, mapEveApprovalValue, withGithubCallerAccess } from "@github-tools/sdk/eve-runtime";
9
11
  import { z } from "zod";
10
12
  import { connectGithubScopesForTools, connectGithubToken, resolveGithubConnector } from "@github-tools/sdk/connect";
11
13
  import { connect } from "@vercel/connect/eve";
12
14
  import { defineDynamic, defineTool, toolOutput } from "eve/tools";
13
- function buildSessionOptions(ctx) {
14
- const { token, connector, connect, preset, include, exclude, overrides, context, author, committer, coAuthors } = extension_default.config;
15
+ function buildSessionOptions(ctx, auth = ctx?.session.auth.current) {
16
+ const { token, connector, connect, preset, include, exclude, overrides, author, committer, coAuthors, guardrails, dryRun } = extension_default.config;
17
+ const context = sessionContext(auth);
15
18
  const includeNames = include;
16
19
  const excludeNames = exclude;
17
20
  return {
@@ -36,7 +39,9 @@ function buildSessionOptions(ctx) {
36
39
  context,
37
40
  author,
38
41
  committer,
39
- coAuthors
42
+ coAuthors,
43
+ guardrails,
44
+ dryRun
40
45
  };
41
46
  }
42
47
  const autoApprovalTools = new Set(AUTO_APPROVAL_TOOLS);
@@ -83,12 +88,30 @@ async function githubUserAuth() {
83
88
  }
84
89
  async function runGithubEveTool(name, input, ctx) {
85
90
  const args = input;
91
+ if (extension_default.config.dryRun && writeToolName(name)) {
92
+ const key = decisionKey(ctx.session.id, ctx.callId);
93
+ const dryRunApproval = dryRunApprovals.get(key);
94
+ dryRunApprovals.delete(key);
95
+ return executeGithubEveTool(name, args, {
96
+ ...buildSessionOptions(ctx),
97
+ dryRunApproval
98
+ });
99
+ }
86
100
  const actAs = actAsFor(name);
87
101
  if (actAs === "app") return executeGithubEveTool(name, args, buildSessionOptions(ctx));
88
102
  const requester = ctx.session.auth.current;
89
103
  const approver = ctx.approval?.responder;
104
+ const approvedByOther = isUser(approver) && !samePrincipal(approver, requester);
105
+ const commenter = actAs === "caller" ? githubCommenter(approvedByOther ? approver : requester) : void 0;
106
+ if (commenter) {
107
+ const options = buildSessionOptions(ctx);
108
+ return executeGithubEveTool(name, args, {
109
+ ...options,
110
+ token: withGithubCallerAccess(options.token, commenter)
111
+ });
112
+ }
90
113
  const auth = await githubUserAuth();
91
- if (isUser(approver) && !samePrincipal(approver, requester)) {
114
+ if (approvedByOther) {
92
115
  const { token } = await approver.getToken(auth);
93
116
  return executeGithubEveTool(name, args, {
94
117
  ...buildSessionOptions(ctx),
@@ -110,7 +133,9 @@ async function runGithubEveApprovalResponse(name, { request, response, auth }) {
110
133
  status: "rejected",
111
134
  reason: "Sign in to approve this GitHub action."
112
135
  };
113
- if (actAsFor(name) === "app") return { status: "allowed" };
136
+ const actAs = actAsFor(name);
137
+ if (actAs === "app") return { status: "allowed" };
138
+ if (actAs === "caller" && githubCommenter(response.principal)) return { status: "allowed" };
114
139
  await auth.getToken(await githubUserAuth());
115
140
  return { status: "allowed" };
116
141
  }
@@ -172,9 +197,30 @@ function configuredApprovalValue(name) {
172
197
  const { requireApproval, overrides } = extension_default.config;
173
198
  return approvalValue(writeTool, requireApproval, overrides?.[name]?.approval);
174
199
  }
200
+ const dryRunApprovals = new Map();
175
201
  async function runGithubEveApproval(name, request, ctx) {
176
202
  const writeTool = writeToolName(name);
177
203
  if (!writeTool) return "not-applicable";
204
+ const reason = githubGuardrailViolation(name, ctx.toolInput, {
205
+ context: sessionContext(ctx.session.auth.current),
206
+ guardrails: extension_default.config.guardrails
207
+ });
208
+ if (reason) return {
209
+ type: "denied",
210
+ reason
211
+ };
212
+ if (!extension_default.config.dryRun) return githubApprovalStatus(name, writeTool, request, ctx);
213
+ const auto = configuredApprovalValue(name) === "auto" && isPersonRequest(ctx) && await cachedAutoApproval(writeTool, request, ctx);
214
+ const status = auto ? void 0 : await githubApprovalStatus(name, writeTool, request, ctx);
215
+ if (status === "denied" || typeof status === "object" && status?.type === "denied") return status;
216
+ dryRunApprovals.set(decisionKey(ctx.session.id, ctx.callId), auto ? {
217
+ required: auto.ask,
218
+ reason: auto.reason
219
+ } : { required: status === true || status === "user-approval" || typeof status === "object" && status?.type === "user-approval" });
220
+ if (dryRunApprovals.size > MAX_CACHED_DECISIONS) dryRunApprovals.delete(dryRunApprovals.keys().next().value);
221
+ return "not-applicable";
222
+ }
223
+ async function githubApprovalStatus(name, writeTool, request, ctx) {
178
224
  const value = configuredApprovalValue(name);
179
225
  if (value === "auto") {
180
226
  if (!isPersonRequest(ctx)) return "user-approval";
@@ -187,10 +233,10 @@ async function runGithubEveApproval(name, request, ctx) {
187
233
  if (isEveApprovalDisabled(value)) return "not-applicable";
188
234
  return mapEveApprovalValue(value)(ctx);
189
235
  }
190
- function describeGithubCall(name, inputSchema, input) {
236
+ function describeGithubCall(name, inputSchema, input, sessionContext) {
191
237
  const fields = inputSchema instanceof z.ZodObject ? inputSchema.shape : {};
192
238
  const { owner, repo, pullNumber, issueNumber, discussionNumber } = {
193
- ...Object.fromEntries(Object.entries(extension_default.config.context ?? {}).filter(([key]) => key in fields)),
239
+ ...Object.fromEntries(Object.entries(sessionContext ?? {}).filter(([key]) => key in fields)),
194
240
  ...input
195
241
  };
196
242
  const action = name.replace(/[A-Z]/g, (letter) => ` ${letter.toLowerCase()}`);
@@ -218,22 +264,27 @@ const PAST_TENSE = {
218
264
  trigger: "Triggered",
219
265
  update: "Updated"
220
266
  };
221
- function describeGithubResult(name, inputSchema, input, output) {
267
+ function describeGithubResult(name, inputSchema, input, output, context) {
222
268
  if (output !== null && typeof output === "object" && "error" in output) {
223
- const label = describeGithubCall(name, inputSchema, input);
269
+ const label = describeGithubCall(name, inputSchema, input, context);
224
270
  return `Couldn't ${label[0].toLowerCase()}${label.slice(1)}`;
225
271
  }
226
272
  if (!writeToolName(name)) return "";
273
+ if (output !== null && typeof output === "object" && "dryRun" in output) {
274
+ const label = describeGithubCall(name, inputSchema, input, context);
275
+ return `Would ${label[0].toLowerCase()}${label.slice(1)}`;
276
+ }
227
277
  const created = output !== null && typeof output === "object" && "number" in output && typeof output.number === "number" ? output.number : void 0;
228
278
  const [verb, ...rest] = describeGithubCall(name, inputSchema, created !== void 0 && input.pullNumber === void 0 && input.issueNumber === void 0 && input.discussionNumber === void 0 ? {
229
279
  ...input,
230
280
  issueNumber: created
231
- } : input).split(" ");
281
+ } : input, context).split(" ");
232
282
  const past = PAST_TENSE[verb.toLowerCase()];
233
283
  return past ? [past, ...rest].join(" ") : "";
234
284
  }
235
285
  var github_default = defineDynamic(async (ctx) => {
236
- const sessionOptions = buildSessionOptions();
286
+ const sessionOptions = buildSessionOptions(void 0, ctx.session.auth.current);
287
+ const { context } = sessionOptions;
237
288
  const { preset, evaluation } = extension_default.config;
238
289
  const messages = await ctx.messages();
239
290
  const request = latestUserText(messages);
@@ -265,12 +316,12 @@ var github_default = defineDynamic(async (ctx) => {
265
316
  inputSchema: entry.inputSchema,
266
317
  approval: {
267
318
  request: (approvalCtx) => runGithubEveApproval(name, request, approvalCtx),
268
- prompt: ({ callId, input }) => approvalPrompt(describeGithubCall(name, entry.inputSchema, input), ctx.session.id, callId),
319
+ prompt: ({ callId, input }) => approvalPrompt(describeGithubCall(name, entry.inputSchema, input, context), ctx.session.id, callId),
269
320
  ...configuredResponse ? { response: (responseCtx) => runConfiguredApprovalResponse(name, configuredResponse, responseCtx) } : extension_default.config.approvers === "anyone" && { response: (responseCtx) => runGithubEveApprovalResponse(name, responseCtx) }
270
321
  },
271
322
  label: {
272
- start: (input) => describeGithubCall(name, entry.inputSchema, input),
273
- complete: (input, output) => describeGithubResult(name, entry.inputSchema, input, output)
323
+ start: (input) => describeGithubCall(name, entry.inputSchema, input, context),
324
+ complete: (input, output) => describeGithubResult(name, entry.inputSchema, input, output, context)
274
325
  },
275
326
  toModelOutput: (output) => runGithubEveToModelOutput(name, output),
276
327
  ...override?.outputSchema !== void 0 && { outputSchema: override.outputSchema },
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@github-tools/eve-extension",
3
- "version": "0.11.0",
3
+ "version": "0.13.0",
4
4
  "description": "GitHub tools for eve, distributed as a mountable eve extension (https://eve.dev/docs/extensions)",
5
5
  "author": "HugoRCD <hugo.richard@vercel.com>",
6
6
  "repository": {
@@ -30,10 +30,15 @@
30
30
  "./tools": {
31
31
  "types": "./dist/tools/index.d.ts",
32
32
  "default": "./dist/tools/index.mjs"
33
+ },
34
+ "./channels": {
35
+ "types": "./channels/dist/index.d.ts",
36
+ "default": "./channels/dist/index.js"
33
37
  }
34
38
  },
35
39
  "files": [
36
- "dist"
40
+ "dist",
41
+ "channels/dist"
37
42
  ],
38
43
  "keywords": [
39
44
  "ai",
@@ -45,8 +50,8 @@
45
50
  ],
46
51
  "license": "MIT",
47
52
  "dependencies": {
48
- "zod": "^4.5.4",
49
- "@github-tools/sdk": "1.20.0"
53
+ "zod": "^4.6.7",
54
+ "@github-tools/sdk": "1.22.0"
50
55
  },
51
56
  "peerDependencies": {
52
57
  "@vercel/connect": ">=2.7.0",
@@ -69,7 +74,7 @@
69
74
  "access": "public"
70
75
  },
71
76
  "scripts": {
72
- "build": "eve extension build",
77
+ "build": "eve extension build && tsc -p tsconfig.channels.json",
73
78
  "lint": "eslint .",
74
79
  "lint:fix": "eslint . --fix",
75
80
  "typecheck": "tsc --noEmit"