@github-tools/eve-extension 0.12.0 → 0.14.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,8 @@ 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 |
121
+ | `attribution` | `boolean \| { footer?, coAuthor? }` (optional) | Credit the GitHub App when a call runs with a person's token, since GitHub then records the person as the author. `createPullRequest` ends the body with `Generated by [<app>](https://github.com/apps/<app>).`, and the commit tools add the App's bot account to `coAuthors`. The App is read from the person's token, once per process. Calls that run as the App add nothing. Default `true`; `false` turns both off |
100
122
  | `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
123
  | `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
124
  | `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 +133,7 @@ extension/
111
133
  ## Build (contributors)
112
134
 
113
135
  ```sh
114
- pnpm --filter @github-tools/eve-extension build # runs `eve extension build`
136
+ pnpm --filter @github-tools/eve-extension build # runs `eve extension build`, then compiles `channels/`
115
137
  ```
116
138
 
117
139
  ## 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
+ }
@@ -64,6 +64,13 @@ export type GithubExtensionActAs = GithubActAs | {
64
64
  };
65
65
  /** Who may answer an approval: only the requester, or any signed-in user. */
66
66
  export type GithubExtensionApprovers = 'requester' | 'anyone';
67
+ /** Which credits `attribution` adds. Each defaults to `true`. */
68
+ export interface GithubExtensionAttribution {
69
+ /** End the body of a pull request with a line saying the App generated it. */
70
+ footer?: boolean;
71
+ /** Add the App's bot account as `Co-authored-by` on commits. */
72
+ coAuthor?: boolean;
73
+ }
67
74
  /** Per-tool overrides, including the tool's own `actAs`. */
68
75
  export type GithubExtensionToolOverrides = {
69
76
  [K in GithubToolName]?: NonNullable<EveToolOverrides[K]> & {
@@ -100,7 +107,10 @@ export interface GithubExtensionConfig {
100
107
  * - `'caller'`: `'user'` when a signed-in user drives the turn, the App when
101
108
  * nobody does (schedules, automations, bots). A user who has not
102
109
  * authorized the App is asked to sign in; the call never falls back to
103
- * the App for them.
110
+ * the App for them. Someone who comments on eve's GitHub channel can't
111
+ * sign in, so their call runs as the App once their own role on the
112
+ * repository it targets allows it: Read for a read, Write for a write.
113
+ * A refused call fails with `github_tools.CALLER_FORBIDDEN`.
104
114
  *
105
115
  * GitHub allows a user-token call only when both the user and the App have
106
116
  * access, so a maintainer can do what a maintainer can, and a reader can
@@ -112,6 +122,21 @@ export interface GithubExtensionConfig {
112
122
  * `'caller'` in a future major version.
113
123
  */
114
124
  actAs?: GithubExtensionActAs;
125
+ /**
126
+ * Credit the GitHub App on what a person writes through it. When a call runs with a person's
127
+ * GitHub token (`actAs: 'user'`, or `'caller'` with a signed-in user), GitHub records that person
128
+ * as the author, so by default:
129
+ *
130
+ * - `createPullRequest` ends the body with `Generated by [<app>](https://github.com/apps/<app>).`
131
+ * - `createOrUpdateFile`, `editFiles`, `mergePullRequest` and `enablePullRequestAutoMerge` add the
132
+ * App's bot account to `coAuthors`, so the commit message carries
133
+ * `Co-authored-by: <app>[bot] <id+<app>[bot]@users.noreply.github.com>`.
134
+ *
135
+ * The App is read from the person's token, so the connector must be backed by a GitHub App.
136
+ * Calls that run as the App add nothing: the App is already their author. Pass `false` to turn
137
+ * both off, or `{ footer, coAuthor }` to pick.
138
+ */
139
+ attribution?: boolean | GithubExtensionAttribution;
115
140
  /**
116
141
  * Who may answer an approval.
117
142
  *
@@ -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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"}
@@ -27,6 +27,10 @@ const configSchema = z.object({
27
27
  write: actAsSchema.optional()
28
28
  })]).optional(),
29
29
  approvers: z.enum(["requester", "anyone"]).optional(),
30
+ attribution: z.union([z.boolean(), z.object({
31
+ footer: z.boolean().optional(),
32
+ coAuthor: z.boolean().optional()
33
+ })]).optional(),
30
34
  connect: z.union([z.record(z.string(), z.unknown()), z.custom((value) => typeof value === "function")]).optional(),
31
35
  preset: z.union([
32
36
  presetNameSchema,
@@ -0,0 +1,10 @@
1
+ import { type EveGithubToolsOptions, type GithubToolName } from '@github-tools/sdk/eve-runtime';
2
+ /**
3
+ * The input and options of a call that runs with a person's `token`, with the App credited as
4
+ * `attribution` asks: a footer on a new pull request, a co-author on a commit.
5
+ */
6
+ export declare function withAttribution(name: GithubToolName, args: Record<string, unknown>, options: EveGithubToolsOptions, token: string): Promise<{
7
+ args: Record<string, unknown>;
8
+ options: EveGithubToolsOptions;
9
+ }>;
10
+ //# sourceMappingURL=attribution.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"attribution.d.ts","sourceRoot":"","sources":["../../../../extension/lib/attribution.ts"],"names":[],"mappings":"AACA,OAAO,EAKL,KAAK,qBAAqB,EAE1B,KAAK,cAAc,EACpB,MAAM,+BAA+B,CAAA;AAsBtC;;;GAGG;AACH,wBAAsB,eAAe,CACnC,IAAI,EAAE,cAAc,EACpB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,OAAO,EAAE,qBAAqB,EAC9B,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC;IAAE,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAAC,OAAO,EAAE,qBAAqB,CAAA;CAAE,CAAC,CAc5E"}
@@ -0,0 +1,55 @@
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
+ import { GITHUB_COMMIT_TOOLS, githubAppBot, githubAppBotIdentity, withGithubAppFooter } from "@github-tools/sdk/eve-runtime";
9
+ import { resolveGithubConnector } from "@github-tools/sdk/connect";
10
+ const bots = new Map();
11
+ async function appBot(token) {
12
+ const connector = await resolveGithubConnector(extension_default.config.connector);
13
+ const cached = bots.get(connector);
14
+ if (cached) return cached;
15
+ const bot = githubAppBot(token);
16
+ bots.set(connector, bot);
17
+ bot.catch(() => bots.delete(connector));
18
+ return bot;
19
+ }
20
+ function credits() {
21
+ const { attribution = true } = extension_default.config;
22
+ if (typeof attribution === "boolean") return {
23
+ footer: attribution,
24
+ coAuthor: attribution
25
+ };
26
+ return {
27
+ footer: attribution.footer ?? true,
28
+ coAuthor: attribution.coAuthor ?? true
29
+ };
30
+ }
31
+ async function withAttribution(name, args, options, token) {
32
+ const { footer, coAuthor } = credits();
33
+ const addFooter = footer && name === "createPullRequest";
34
+ const addCoAuthor = coAuthor && GITHUB_COMMIT_TOOLS.has(name);
35
+ if (!addFooter && !addCoAuthor) return {
36
+ args,
37
+ options: {
38
+ ...options,
39
+ token
40
+ }
41
+ };
42
+ const bot = await appBot(token);
43
+ return {
44
+ args: addFooter ? {
45
+ ...args,
46
+ body: withGithubAppFooter(args.body, bot)
47
+ } : args,
48
+ options: {
49
+ ...options,
50
+ token,
51
+ ...addCoAuthor && { coAuthors: [...options.coAuthors ?? [], githubAppBotIdentity(bot)] }
52
+ }
53
+ };
54
+ }
55
+ export { withAttribution };
@@ -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 };
@@ -1 +1 @@
1
- {"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../../extension/tools/github.ts"],"names":[],"mappings":";AAuXA,wBAsDE"}
1
+ {"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../../extension/tools/github.ts"],"names":[],"mappings":";AAkYA,wBAsDE"}
@@ -4,13 +4,15 @@ 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 { withAttribution } from "../lib/attribution.mjs";
8
+ import { githubCommenter } from "../lib/commenter.mjs";
7
9
  import { sessionContext } from "../lib/context.mjs";
8
10
  import extension_default from "../extension.mjs";
9
- import { AUTO_APPROVAL_TOOLS, GITHUB_TOOL_NAMES, GITHUB_WRITE_TOOLS, autoApprovalDecision, evaluatePresets, evaluateTools, executeGithubEveTool, fallbackPresets, fallbackTools, formatGithubEveToolOutput, githubGuardrailViolation, githubToolsErrors, isEveApprovalDisabled, latestUserText, listEveToolDescriptors, mapEveApprovalValue } from "@github-tools/sdk/eve-runtime";
11
+ 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";
10
12
  import { z } from "zod";
11
13
  import { connectGithubScopesForTools, connectGithubToken, resolveGithubConnector } from "@github-tools/sdk/connect";
12
14
  import { connect } from "@vercel/connect/eve";
13
- import { defineDynamic, defineTool, toolOutput } from "eve/tools";
15
+ import { defineDynamic, defineTool } from "eve/tools";
14
16
  function buildSessionOptions(ctx, auth = ctx?.session.auth.current) {
15
17
  const { token, connector, connect, preset, include, exclude, overrides, author, committer, coAuthors, guardrails, dryRun } = extension_default.config;
16
18
  const context = sessionContext(auth);
@@ -85,6 +87,10 @@ function samePrincipal(a, b) {
85
87
  async function githubUserAuth() {
86
88
  return connect(await resolveGithubConnector(extension_default.config.connector));
87
89
  }
90
+ async function runAsUser(name, input, ctx, token) {
91
+ const { args, options } = await withAttribution(name, input, buildSessionOptions(ctx), token);
92
+ return executeGithubEveTool(name, args, options);
93
+ }
88
94
  async function runGithubEveTool(name, input, ctx) {
89
95
  const args = input;
90
96
  if (extension_default.config.dryRun && writeToolName(name)) {
@@ -100,22 +106,28 @@ async function runGithubEveTool(name, input, ctx) {
100
106
  if (actAs === "app") return executeGithubEveTool(name, args, buildSessionOptions(ctx));
101
107
  const requester = ctx.session.auth.current;
102
108
  const approver = ctx.approval?.responder;
103
- const auth = await githubUserAuth();
104
- if (isUser(approver) && !samePrincipal(approver, requester)) {
105
- const { token } = await approver.getToken(auth);
109
+ const approvedByOther = isUser(approver) && !samePrincipal(approver, requester);
110
+ const commenter = actAs === "caller" ? githubCommenter(approvedByOther ? approver : requester) : void 0;
111
+ if (commenter) {
112
+ const options = buildSessionOptions(ctx);
106
113
  return executeGithubEveTool(name, args, {
107
- ...buildSessionOptions(ctx),
108
- token
114
+ ...options,
115
+ token: withGithubCallerAccess(options.token, commenter)
109
116
  });
110
117
  }
118
+ const auth = await githubUserAuth();
119
+ if (approvedByOther) {
120
+ const { token } = await approver.getToken(auth);
121
+ return runAsUser(name, args, ctx, token);
122
+ }
111
123
  if (actAs === "caller" && !isUser(requester)) return executeGithubEveTool(name, args, buildSessionOptions(ctx));
112
124
  const { token } = await ctx.getToken(auth);
113
- const result = await executeGithubEveTool(name, args, {
114
- ...buildSessionOptions(ctx),
115
- token
116
- });
117
- if (isUnauthorized(result)) ctx.requireAuth(auth);
118
- return result;
125
+ try {
126
+ return await runAsUser(name, args, ctx, token);
127
+ } catch (error) {
128
+ if (isUnauthorized(error)) ctx.requireAuth(auth);
129
+ throw error;
130
+ }
119
131
  }
120
132
  async function runGithubEveApprovalResponse(name, { request, response, auth }) {
121
133
  if (response.decision === "deny") return { status: "allowed" };
@@ -123,7 +135,9 @@ async function runGithubEveApprovalResponse(name, { request, response, auth }) {
123
135
  status: "rejected",
124
136
  reason: "Sign in to approve this GitHub action."
125
137
  };
126
- if (actAsFor(name) === "app") return { status: "allowed" };
138
+ const actAs = actAsFor(name);
139
+ if (actAs === "app") return { status: "allowed" };
140
+ if (actAs === "caller" && githubCommenter(response.principal)) return { status: "allowed" };
127
141
  await auth.getToken(await githubUserAuth());
128
142
  return { status: "allowed" };
129
143
  }
@@ -136,20 +150,15 @@ function configuredApprovalResponse(name) {
136
150
  const value = configuredApprovalValue(name);
137
151
  return typeof value === "object" ? value.response : void 0;
138
152
  }
139
- function isUnauthorized(result) {
140
- if (!isErrorResult(result)) return false;
141
- const { error } = result;
142
- return typeof error === "object" && error !== null && "code" in error && error.code === githubToolsErrors.UNAUTHORIZED.code;
153
+ function isUnauthorized(error) {
154
+ const cause = error instanceof Error ? error.cause : void 0;
155
+ return typeof cause === "object" && cause !== null && "code" in cause && cause.code === githubToolsErrors.UNAUTHORIZED.code;
143
156
  }
144
157
  function runGithubEveToModelOutput(name, output) {
145
158
  const custom = buildSessionOptions().overrides?.[name]?.toModelOutput;
146
159
  if (custom) return custom(output);
147
- if (isErrorResult(output)) return toolOutput.errorText(JSON.stringify({ error: output.error }));
148
160
  return formatGithubEveToolOutput(name, output);
149
161
  }
150
- function isErrorResult(output) {
151
- return output != null && typeof output === "object" && !Array.isArray(output) && "error" in output && output.error != null;
152
- }
153
162
  function isPersonRequest(ctx) {
154
163
  return ctx.session.parent === void 0 && ctx.session.auth.current?.principalType !== "service";
155
164
  }
@@ -253,10 +262,6 @@ const PAST_TENSE = {
253
262
  update: "Updated"
254
263
  };
255
264
  function describeGithubResult(name, inputSchema, input, output, context) {
256
- if (output !== null && typeof output === "object" && "error" in output) {
257
- const label = describeGithubCall(name, inputSchema, input, context);
258
- return `Couldn't ${label[0].toLowerCase()}${label.slice(1)}`;
259
- }
260
265
  if (!writeToolName(name)) return "";
261
266
  if (output !== null && typeof output === "object" && "dryRun" in output) {
262
267
  const label = describeGithubCall(name, inputSchema, input, context);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@github-tools/eve-extension",
3
- "version": "0.12.0",
3
+ "version": "0.14.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.21.0"
53
+ "zod": "^4.6.7",
54
+ "@github-tools/sdk": "1.23.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"