@github-tools/eve-extension 0.1.0 → 0.3.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
@@ -1,4 +1,4 @@
1
- <img src="https://github.com/vercel-labs/github-tools/blob/main/assets/banner.jpg" width="100%" alt="GitHub Tools banner" />
1
+ <img src="https://github.com/vercel-labs/github-tools/blob/main/assets/banner.jpg" width="100%" alt="GitHub tools banner" />
2
2
 
3
3
  # @github-tools/eve-extension
4
4
 
@@ -7,11 +7,11 @@
7
7
  [![TypeScript](https://img.shields.io/badge/TypeScript-black?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
8
8
  [![license](https://img.shields.io/github/license/vercel-labs/github-tools?color=black)](https://github.com/vercel-labs/github-tools/blob/main/LICENSE)
9
9
 
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 top of [`@github-tools/sdk/eve`](../github-tools#eve).
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](https://github-tools.com/frameworks/eve#eve-extension)**
12
+ Docs: **[github-tools.com/frameworks/eve-extension](https://github-tools.com/frameworks/eve-extension)**
13
13
 
14
- This is the recommended direction for adding GitHub tools to an eve agent going forward. The direct [`@github-tools/sdk/eve`](../github-tools#eve) import remains supported for agents that prefer importing tools directly into `agent/tools/`.
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
 
16
16
  ## Installation
17
17
 
@@ -34,15 +34,44 @@ import githubExtension from '@github-tools/eve-extension'
34
34
  export default githubExtension({
35
35
  connector: 'github/my-connector', // or token: process.env.GITHUB_TOKEN
36
36
  preset: 'code-review',
37
+ context: { owner: 'vercel-labs', repo: 'github-tools' },
37
38
  requireApproval: {
38
39
  addPullRequestComment: ({ toolInput }) => toolInput?.owner !== 'vercel-labs',
39
40
  },
40
41
  })
41
42
  ```
42
43
 
43
- > `code-review` pairs cleanly with a Connect `connector` — `maintainer` and `repo-explorer` include gist tools, and GitHub only grants gist access to user access tokens, never the installation tokens Connect mints, so gist calls 403 over Connect. Write tools already require approval via `always()` by default, so a plain `{ someTool: true }` is a no-op — use a predicate (as above) when you actually want to narrow or loosen the default.
44
+ > `code-review` pairs cleanly with a Connect `connector`. `maintainer` and `repo-explorer` include gist tools, and GitHub only grants gist access to user access tokens, never the installation tokens Connect mints, so gist calls 403 over Connect. Write tools already require approval via `always()` by default, so a plain `{ someTool: true }` is a no-op, use a predicate (as above) when you actually want to narrow or loosen the default.
44
45
 
45
- Tools are exposed to the model as `<namespace>__<toolName>`, where `<namespace>` comes from the mount file's name — `agent/extensions/github.ts` yields `github__listPullRequests`, `github__createIssue`, and so on.
46
+ Tools are registered with **inline** `execute` handlers in the extension package so they survive multi-turn durable eve Workflow replay (see [#51](https://github.com/vercel-labs/github-tools/issues/51)). Do not use the deprecated `@github-tools/sdk/connect/eve` one-liner for durable Slack/multi-turn agents.
47
+
48
+ `connector` also accepts a `() => string | Promise<string>` resolver, so the same config can pick a connector dynamically (e.g. by environment):
49
+
50
+ ```ts
51
+ export default githubExtension({
52
+ connector: () => (process.env.VERCEL_ENV === 'production' ? 'github/prod-connector' : 'github/preview-connector'),
53
+ preset: 'code-review',
54
+ })
55
+ ```
56
+
57
+ Tools are exposed to the model as `<namespace>__<toolName>`, where `<namespace>` comes from the mount file's name: `agent/extensions/github.ts` yields `github__listPullRequests`, `github__createIssue`, and so on.
58
+
59
+ To hand-pick an exact set of tools instead of a preset, pass `include`:
60
+
61
+ ```ts
62
+ export default githubExtension({
63
+ include: ['getRepository', 'listPullRequests', 'mergePullRequest'],
64
+ })
65
+ ```
66
+
67
+ `include` **adds** to `preset` (union), use it to pull in a tool a preset is missing. `exclude` **removes** tool names from the resolved `preset` + `include` set, use it to drop a couple of tools from a larger preset:
68
+
69
+ ```ts
70
+ export default githubExtension({
71
+ preset: 'maintainer',
72
+ exclude: ['createRepository', 'deleteGist'],
73
+ })
74
+ ```
46
75
 
47
76
  See the runnable consumer at [`examples/eve-extension-agent`](../../examples/eve-extension-agent).
48
77
 
@@ -50,9 +79,9 @@ See the runnable consumer at [`examples/eve-extension-agent`](../../examples/eve
50
79
 
51
80
  ```
52
81
  extension/
53
- extension.ts # defineExtension() config schema (token, connector, preset, requireApproval, ...)
82
+ extension.ts # defineExtension() config schema (token, connector, preset, include, exclude, requireApproval, ...)
54
83
  tools/
55
- github.ts # defineDynamic() returning buildEveToolMap(...) filtered by preset
84
+ github.ts # defineDynamic() returning buildEveToolMap(...) scoped by preset/include/exclude
56
85
  ```
57
86
 
58
87
  ## Config schema (`extension/extension.ts`)
@@ -60,9 +89,12 @@ extension/
60
89
  | Field | Type | Notes |
61
90
  |---|---|---|
62
91
  | `token` | `string?` | Falls back to `GITHUB_TOKEN` when omitted and `connector` is not set |
63
- | `connector` | `string?` | Vercel Connect connector name; takes priority over `token` |
92
+ | `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` |
64
93
  | `connect` | `record?` | Passed through to `getToken` when `connector` is set |
65
- | `preset` | preset name or array | `code-review`, `issue-triage`, `ci-ops`, `repo-explorer`, `maintainer` |
94
+ | `preset` | preset name or array | `code-review`, `issue-triage`, `ci-ops`, `repo-explorer`, `security-audit`, `release-manager`, `discussion-moderator`, `notification-inbox`, `pr-author`, `maintainer` |
95
+ | `include` | `string[]?` | Tool names to add on top of `preset` (union), or the full set standalone |
96
+ | `exclude` | `string[]?` | Tool names to remove from the resolved `preset` + `include` set |
97
+ | `context` | `{ owner?, repo?, pullNumber?, issueNumber?, ref? }?` | Default working context for tool inputs and schemas |
66
98
  | `requireApproval` | `boolean \| record` | Global or per-tool; per-tool values may be predicate functions |
67
99
  | `overrides` | `record` | Per-tool `description` / `approval` / `toModelOutput` / `outputSchema` |
68
100
  | `author` / `committer` / `coAuthors` | commit identity | Attribution for commit-creating tools |
@@ -1,11 +1,11 @@
1
1
  {
2
2
  "kind": "eve-extension",
3
3
  "formatVersion": 1,
4
- "builtWithEve": "0.26.2",
4
+ "builtWithEve": "0.30.6",
5
5
  "requires": {
6
6
  "extension": 1,
7
- "tool": 1,
8
- "dynamicTool": 2,
7
+ "tool": 5,
8
+ "dynamicTool": 8,
9
9
  "config": 1
10
10
  }
11
11
  }
@@ -1,35 +1,65 @@
1
+ import type { GithubConnectorInput } from '@github-tools/sdk/connect';
2
+ import { type CommitIdentity, type EveApprovalConfig, type EveToolOverrides, type GithubToolName, type GithubToolPreset } from '@github-tools/sdk/eve-runtime';
1
3
  import { z } from 'zod';
2
- declare const _default: import("eve/extension").ExtensionHandle<z.ZodObject<{
3
- token: z.ZodOptional<z.ZodString>;
4
- connector: z.ZodOptional<z.ZodString>;
5
- connect: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
6
- preset: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
7
- "code-review": "code-review";
8
- "issue-triage": "issue-triage";
9
- "ci-ops": "ci-ops";
10
- "repo-explorer": "repo-explorer";
11
- maintainer: "maintainer";
12
- }>, z.ZodArray<z.ZodEnum<{
13
- "code-review": "code-review";
14
- "issue-triage": "issue-triage";
15
- "ci-ops": "ci-ops";
16
- "repo-explorer": "repo-explorer";
17
- maintainer: "maintainer";
18
- }>>]>>;
19
- requireApproval: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodRecord<z.ZodString, z.ZodUnknown>]>>;
20
- overrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
21
- author: z.ZodOptional<z.ZodObject<{
22
- name: z.ZodString;
23
- email: z.ZodString;
24
- }, z.core.$strip>>;
25
- committer: z.ZodOptional<z.ZodObject<{
26
- name: z.ZodString;
27
- email: z.ZodString;
28
- }, z.core.$strip>>;
29
- coAuthors: z.ZodOptional<z.ZodArray<z.ZodObject<{
30
- name: z.ZodString;
31
- email: z.ZodString;
32
- }, z.core.$strip>>>;
33
- }, z.core.$strip>>;
4
+ /**
5
+ * Default owner / repo / PR / issue / ref for tool inputs.
6
+ * Matching fields become optional and fill from this context when omitted.
7
+ */
8
+ export interface GithubExtensionContext {
9
+ /** Repository owner (org or user login). */
10
+ owner?: string;
11
+ /** Repository name. */
12
+ repo?: string;
13
+ /** Default pull request number for PR tools. */
14
+ pullNumber?: number;
15
+ /** Default issue number for issue tools. */
16
+ issueNumber?: number;
17
+ /** Default git ref (branch, tag, or SHA). */
18
+ ref?: string;
19
+ }
20
+ /**
21
+ * Config passed to `githubExtension({ ... })` at the agent mount site.
22
+ * Declared as an interface (not only a Zod schema) so IDE hovers show JSDoc.
23
+ */
24
+ export interface GithubExtensionConfig {
25
+ /** GitHub PAT. Falls back to `GITHUB_TOKEN` when omitted and `connector` is not set. */
26
+ token?: string;
27
+ /**
28
+ * Vercel Connect connector name (e.g. `github/my-connector`), or a
29
+ * `() => string | Promise<string>` resolver for picking one dynamically
30
+ * (e.g. per environment or tenant). Takes priority over `token`.
31
+ */
32
+ connector?: GithubConnectorInput;
33
+ /** Vercel Connect token params passed through to `getToken` when `connector` is set. */
34
+ connect?: Record<string, unknown>;
35
+ /** Restrict tools to a preset (or array of presets). Prefer a focused preset; omit or use `maintainer` for the full catalog. */
36
+ preset?: GithubToolPreset | GithubToolPreset[];
37
+ /**
38
+ * Hand-pick tool names to add on top of `preset` (or standalone, without `preset`).
39
+ * When combined with `preset`, the effective set is the union of both.
40
+ */
41
+ include?: GithubToolName[];
42
+ /** Remove specific tool names from the resolved set, applied after `preset` + `include`. */
43
+ exclude?: GithubToolName[];
44
+ /**
45
+ * Default owner / repo / pullNumber / issueNumber / ref for tool inputs
46
+ * (matching fields become optional and fill from context when omitted).
47
+ */
48
+ context?: GithubExtensionContext;
49
+ /**
50
+ * Global boolean or per-tool approval config.
51
+ * Per-tool values may be `'once'`, `'always'`, `'never'`, or predicate functions.
52
+ */
53
+ requireApproval?: EveApprovalConfig;
54
+ /** Per-tool overrides (`description`, `approval`, `toModelOutput`, `outputSchema`). */
55
+ overrides?: EveToolOverrides;
56
+ /** Default author for commit-creating tools. */
57
+ author?: CommitIdentity;
58
+ /** Default committer for commit-creating tools. */
59
+ committer?: CommitIdentity;
60
+ /** Co-authors to attribute on commits created by tools. */
61
+ coAuthors?: CommitIdentity[];
62
+ }
63
+ declare const _default: import("eve/extension").ExtensionHandle<z.ZodType<GithubExtensionConfig, GithubExtensionConfig, z.core.$ZodTypeInternals<GithubExtensionConfig, GithubExtensionConfig>>>;
34
64
  export default _default;
35
65
  //# sourceMappingURL=extension.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../extension/extension.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AASvB,wBAkBE"}
1
+ {"version":3,"file":"extension.d.ts","sourceRoot":"","sources":["../../../extension/extension.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,2BAA2B,CAAA;AACrE,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,gBAAgB,EACrB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,+BAA+B,CAAA;AAEtC,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB;;;GAGG;AACH,MAAM,WAAW,sBAAsB;IACrC,4CAA4C;IAC5C,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,uBAAuB;IACvB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,gDAAgD;IAChD,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,4CAA4C;IAC5C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,6CAA6C;IAC7C,GAAG,CAAC,EAAE,MAAM,CAAA;CACb;AAED;;;GAGG;AACH,MAAM,WAAW,qBAAqB;IACpC,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAA;IACd;;;;OAIG;IACH,SAAS,CAAC,EAAE,oBAAoB,CAAA;IAChC,wFAAwF;IACxF,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACjC,gIAAgI;IAChI,MAAM,CAAC,EAAE,gBAAgB,GAAG,gBAAgB,EAAE,CAAA;IAC9C;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,EAAE,CAAA;IAC1B,4FAA4F;IAC5F,OAAO,CAAC,EAAE,cAAc,EAAE,CAAA;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,sBAAsB,CAAA;IAChC;;;OAGG;IACH,eAAe,CAAC,EAAE,iBAAiB,CAAA;IACnC,uFAAuF;IACvF,SAAS,CAAC,EAAE,gBAAgB,CAAA;IAC5B,gDAAgD;IAChD,MAAM,CAAC,EAAE,cAAc,CAAA;IACvB,mDAAmD;IACnD,SAAS,CAAC,EAAE,cAAc,CAAA;IAC1B,2DAA2D;IAC3D,SAAS,CAAC,EAAE,cAAc,EAAE,CAAA;CAC7B;;AA4CD,wBAEE"}
@@ -3,6 +3,7 @@ import { dirname as __eveDirname } from "node:path";
3
3
  import { createRequire as __eveCreateRequire } from "node:module";
4
4
  __eveDirname(__eveFileURLToPath(import.meta.url));
5
5
  __eveCreateRequire(import.meta.url);
6
+ import { GITHUB_TOOL_NAMES } from "@github-tools/sdk/eve-runtime";
6
7
  import { defineExtension } from "eve/extension";
7
8
  import { z } from "zod";
8
9
  const presetNameSchema = z.enum([
@@ -10,17 +11,32 @@ const presetNameSchema = z.enum([
10
11
  "issue-triage",
11
12
  "ci-ops",
12
13
  "repo-explorer",
14
+ "security-audit",
15
+ "release-manager",
16
+ "discussion-moderator",
17
+ "notification-inbox",
18
+ "pr-author",
13
19
  "maintainer"
14
20
  ]);
21
+ const toolNameSchema = z.enum(Object.values(GITHUB_TOOL_NAMES));
15
22
  const commitIdentitySchema = z.object({
16
23
  name: z.string(),
17
24
  email: z.string()
18
25
  });
19
26
  var extension_default = defineExtension({ config: z.object({
20
27
  token: z.string().optional(),
21
- connector: z.string().optional(),
28
+ connector: z.custom((value) => typeof value === "string" || typeof value === "function").optional(),
22
29
  connect: z.record(z.string(), z.unknown()).optional(),
23
30
  preset: z.union([presetNameSchema, z.array(presetNameSchema)]).optional(),
31
+ include: z.array(toolNameSchema).optional(),
32
+ exclude: z.array(toolNameSchema).optional(),
33
+ context: z.object({
34
+ owner: z.string().optional(),
35
+ repo: z.string().optional(),
36
+ pullNumber: z.number().optional(),
37
+ issueNumber: z.number().optional(),
38
+ ref: z.string().optional()
39
+ }).optional(),
24
40
  requireApproval: z.union([z.boolean(), z.record(z.string(), z.unknown())]).optional(),
25
41
  overrides: z.record(z.string(), z.unknown()).optional(),
26
42
  author: commitIdentitySchema.optional(),
@@ -1,3 +1,4 @@
1
- declare const _default: import("eve/tools").DynamicSentinel<Partial<Record<import("@github-tools/sdk/eve").GithubToolName, import("eve/tools").ToolDefinition<unknown, unknown>>>>;
1
+ import { type ToolDefinition } from 'eve/tools';
2
+ declare const _default: import("eve/tools").DynamicSentinel<Record<string, ToolDefinition<unknown, unknown>>>;
2
3
  export default _default;
3
4
  //# sourceMappingURL=github.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../../extension/tools/github.ts"],"names":[],"mappings":";AAKA,wBAoBE"}
1
+ {"version":3,"file":"github.d.ts","sourceRoot":"","sources":["../../../../extension/tools/github.ts"],"names":[],"mappings":"AAWA,OAAO,EAA6B,KAAK,cAAc,EAAE,MAAM,WAAW,CAAA;;AAa1E,wBAiEE"}
@@ -4,22 +4,46 @@ import { createRequire as __eveCreateRequire } from "node:module";
4
4
  __eveDirname(__eveFileURLToPath(import.meta.url));
5
5
  __eveCreateRequire(import.meta.url);
6
6
  import extension_default from "../extension.mjs";
7
+ import { executeGithubEveTool, listEveToolDescriptors, mapEveApprovalValue, resolveEveApproval } from "@github-tools/sdk/eve-runtime";
7
8
  import { connectGithubToken } from "@github-tools/sdk/connect";
8
- import { buildEveToolMap } from "@github-tools/sdk/eve";
9
- import { defineDynamic } from "eve/tools";
9
+ import { defineDynamic, defineTool } from "eve/tools";
10
+ let sessionOptions = {};
11
+ async function runGithubEveTool(name, input) {
12
+ return executeGithubEveTool(name, input, sessionOptions);
13
+ }
10
14
  var github_default = defineDynamic({ events: { "session.started": async () => {
11
- const { token, connector, connect, preset, requireApproval, overrides, author, committer, coAuthors } = extension_default.config;
12
- return buildEveToolMap({
15
+ const { token, connector, connect, preset, include, exclude, requireApproval, overrides, context, author, committer, coAuthors } = extension_default.config;
16
+ sessionOptions = {
13
17
  token: connector ? connectGithubToken(connector, {
14
18
  preset,
15
19
  params: connect
16
20
  }) : token,
17
21
  preset,
22
+ include,
23
+ exclude,
18
24
  requireApproval,
19
25
  overrides,
26
+ context,
20
27
  author,
21
28
  committer,
22
29
  coAuthors
23
- });
30
+ };
31
+ const descriptors = listEveToolDescriptors(sessionOptions);
32
+ const tools = {};
33
+ const toolOverrides = sessionOptions.overrides;
34
+ for (const entry of descriptors) {
35
+ const name = entry.name;
36
+ const override = toolOverrides?.[name];
37
+ tools[name] = defineTool({
38
+ description: override?.description ?? entry.description,
39
+ inputSchema: entry.inputSchema,
40
+ ...entry.writeTool && { approval: resolveEveApproval(entry.writeTool, sessionOptions.requireApproval) },
41
+ ...override?.approval !== void 0 && { approval: mapEveApprovalValue(override.approval) },
42
+ ...override?.toModelOutput !== void 0 ? { toModelOutput: override.toModelOutput } : entry.toModelOutput ? { toModelOutput: entry.toModelOutput } : {},
43
+ ...override?.outputSchema !== void 0 && { outputSchema: override.outputSchema },
44
+ execute: async (input) => runGithubEveTool(name, input)
45
+ });
46
+ }
47
+ return tools;
24
48
  } } });
25
49
  export { github_default as default };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@github-tools/eve-extension",
3
- "version": "0.1.0",
3
+ "version": "0.3.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": {
@@ -46,7 +46,7 @@
46
46
  "license": "MIT",
47
47
  "dependencies": {
48
48
  "zod": "^4.3.6",
49
- "@github-tools/sdk": "1.8.2"
49
+ "@github-tools/sdk": "1.10.0"
50
50
  },
51
51
  "peerDependencies": {
52
52
  "@vercel/connect": ">=0.3.2",
@@ -58,12 +58,12 @@
58
58
  }
59
59
  },
60
60
  "devDependencies": {
61
- "@types/node": "^25.6.0",
62
- "@vercel/connect": "^0.4.2",
63
- "eslint": "^10.3.0",
64
- "eve": "^0.26.2",
61
+ "@types/node": "^26.1.2",
62
+ "@vercel/connect": "^0.6.1",
63
+ "eslint": "^10.8.0",
64
+ "eve": "^0.30.6",
65
65
  "typescript": "^6.0.3",
66
- "typescript-eslint": "^8.59.2"
66
+ "typescript-eslint": "^8.65.0"
67
67
  },
68
68
  "publishConfig": {
69
69
  "access": "public"