@inkeep/agents-api 0.0.1 → 0.43.0

package/dist/.well-known/workflow/v1/step.cjs.debug.json

@@ -1,8 +1,6 @@
 {
   "stepFiles": [
-    "/Users/andrew/Documents/code/agents/agents/agents-api/src/domains/evals/workflow/functions/runDatasetItem.ts",
-    "/Users/andrew/Documents/code/agents/agents/agents-api/dist/domains/evals/workflow/functions/evaluateConversation.js",
-    "/Users/andrew/Documents/code/agents/agents/agents-api/dist/domains/evals/workflow/functions/runDatasetItem.js",
-    "/Users/andrew/Documents/code/agents/agents/agents-api/src/domains/evals/workflow/functions/evaluateConversation.ts"
+    "/home/runner/work/agents/agents/agents-api/src/domains/evals/workflow/functions/evaluateConversation.ts",
+    "/home/runner/work/agents/agents/agents-api/src/domains/evals/workflow/functions/runDatasetItem.ts"
   ]
 }

package/dist/_virtual/rolldown_runtime.js

@@ -0,0 +1,7 @@
+import { createRequire } from "node:module";
+
+//#region rolldown:runtime
+var __require = /* @__PURE__ */ createRequire(import.meta.url);
+
+//#endregion
+export { __require };

package/dist/createApp.js

@@ -2,8 +2,10 @@ import { getLogger } from "./logger.js";
 import { env } from "./env.js";
 import { evalRoutes } from "./domains/evals/index.js";
 import { workflowRoutes } from "./domains/evals/workflow/routes.js";
+import { githubRoutes } from "./domains/github/index.js";
 import { sessionAuth, sessionContext } from "./middleware/sessionAuth.js";
 import { manageRoutes } from "./domains/manage/index.js";
+import mcp_default from "./domains/mcp/routes/mcp.js";
 import { flushBatchProcessor } from "./instrumentation.js";
 import { runRoutes } from "./domains/run/index.js";
 import { authCorsConfig, defaultCorsConfig, playgroundCorsConfig, runCorsConfig, signozCorsConfig } from "./middleware/cors.js";
@@ -18,7 +20,8 @@ import { evalApiKeyAuth } from "./middleware/evalsAuth.js";
 import { projectConfigMiddleware, projectConfigMiddlewareExcept } from "./middleware/projectConfig.js";
 import { executionBaggageMiddleware } from "./middleware/tracing.js";
 import { setupOpenAPIRoutes } from "./openapi.js";
-import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { healthChecksHandler } from "./routes/healthChecks.js";
+import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
 import { Hono } from "hono";
 import { cors } from "hono/cors";
 import { requestId } from "hono/request-id";
@@ -33,6 +36,11 @@ const isWebhookRoute = (path) => {
 function createAgentsHono(config) {
 	const { serverConfig, credentialStores, auth, sandboxConfig } = config;
 	const app = new OpenAPIHono();
+	const CapabilitiesResponseSchema = z.object({ sandbox: z.object({
+		configured: z.boolean().describe("Whether a sandbox provider is configured. Required for Function Tools execution."),
+		provider: z.enum(["native", "vercel"]).optional().describe("The configured sandbox provider, if enabled."),
+		runtime: z.enum(["node22", "typescript"]).optional().describe("The configured sandbox runtime, if enabled.")
+	}).describe("Sandbox execution capabilities (used by Function Tools).") }).describe("Optional server capabilities and configuration.").openapi("CapabilitiesResponseSchema");
 	app.use("*", requestId());
 	if (auth) {
 		app.use("/api/auth/*", cors(authCorsConfig));
@@ -48,6 +56,7 @@ function createAgentsHono(config) {
 		if (c.req.path.startsWith("/run/")) return next();
 		if (c.req.path.includes("/playground/token")) return next();
 		if (c.req.path.includes("/signoz/")) return next();
+		if (c.req.path.includes("/api/github/")) return next();
 		return cors(defaultCorsConfig)(c, next);
 	});
 	app.use("*", async (c, next) => {
@@ -82,20 +91,11 @@ function createAgentsHono(config) {
 	}));
 	app.onError(errorHandler);
 	app.use("*", sessionContext());
-	app.openapi(createRoute({
-		method: "get",
-		path: "/health",
-		operationId: "health",
-		summary: "Health check",
-		description: "Check if the management service is healthy",
-		responses: { 204: { description: "Service is healthy" } }
-	}), (c) => {
-		return c.body(null, 204);
-	});
+	app.route("/", healthChecksHandler);
 	app.openapi(createRoute({
 		method: "get",
 		path: "/api/workflow/process",
-		tags: ["workflow"],
+		tags: ["Workflows"],
 		summary: "Process workflow jobs",
 		description: "Keeps the workflow worker active to process queued jobs (called by cron)",
 		responses: { 200: { description: "Processing complete" } }
@@ -114,6 +114,32 @@ function createAgentsHono(config) {
 		if (c.req.header("Authorization")?.startsWith("Bearer ")) return manageApiKeyAuth()(c, next);
 		return sessionAuth()(c, next);
 	});
+	app.use("/manage/capabilities", async (c, next) => {
+		if (!auth || env.DISABLE_AUTH || isTestEnvironment()) {
+			await next();
+			return;
+		}
+		if (c.req.header("Authorization")?.startsWith("Bearer ")) return manageApiKeyAuth()(c, next);
+		return sessionAuth()(c, next);
+	});
+	app.openapi(createRoute({
+		method: "get",
+		path: "/manage/capabilities",
+		operationId: "capabilities",
+		summary: "Get server capabilities",
+		description: "Get information about optional server-side capabilities and configuration.",
+		responses: { 200: {
+			description: "Server capabilities",
+			content: { "application/json": { schema: CapabilitiesResponseSchema } }
+		} }
+	}), (c) => {
+		if (!sandboxConfig) return c.json({ sandbox: { configured: false } });
+		return c.json({ sandbox: {
+			configured: true,
+			provider: sandboxConfig.provider,
+			runtime: sandboxConfig.runtime
+		} });
+	});
 	if (env.DISABLE_AUTH || isTestEnvironment()) app.use("/manage/tenants/:tenantId/*", async (c, next) => {
 		const tenantId = c.req.param("tenantId");
 		if (tenantId) {
@@ -156,6 +182,8 @@ function createAgentsHono(config) {
 		return fetch(forwardedRequest);
 	});
 	app.route("/evals", evalRoutes);
+	app.route("/api/github", githubRoutes);
+	app.route("/mcp", mcp_default);
 	setupOpenAPIRoutes(app);
 	app.use("/run/*", async (_c, next) => {
 		await next();

package/dist/domains/evals/api/.well-known/workflow/v1/flow.d.ts

@@ -0,0 +1,4 @@
+//#region src/domains/evals/api/.well-known/workflow/v1/flow.d.ts
+declare function handler(req: Request): Promise<Response>;
+//#endregion
+export { handler as default };

package/dist/domains/evals/api/.well-known/workflow/v1/flow.js

@@ -0,0 +1,12 @@
+import { createRequire } from "node:module";
+
+//#region src/domains/evals/api/.well-known/workflow/v1/flow.ts
+console.log("[WF CONSUMER] flow.ts loaded", (/* @__PURE__ */ new Date()).toISOString());
+const flowModule = createRequire(import.meta.url)("../../../../dist/.well-known/workflow/v1/flow.cjs");
+async function handler(req) {
+	console.log("[WF CONSUMER HIT] flow.ts", (/* @__PURE__ */ new Date()).toISOString(), req.method, req.url);
+	return flowModule.default(req);
+}
+
+//#endregion
+export { handler as default };

package/dist/domains/evals/api/.well-known/workflow/v1/step.d.ts

@@ -0,0 +1,4 @@
+//#region src/domains/evals/api/.well-known/workflow/v1/step.d.ts
+declare function handler(req: Request): Promise<Response>;
+//#endregion
+export { handler as default };

package/dist/domains/evals/api/.well-known/workflow/v1/step.js

@@ -0,0 +1,12 @@
+import { createRequire } from "node:module";
+
+//#region src/domains/evals/api/.well-known/workflow/v1/step.ts
+console.log("[WF CONSUMER] step.ts loaded", (/* @__PURE__ */ new Date()).toISOString());
+const stepModule = createRequire(import.meta.url)("../../../../dist/.well-known/workflow/v1/step.cjs");
+async function handler(req) {
+	console.log("[WF CONSUMER HIT] step.ts", (/* @__PURE__ */ new Date()).toISOString(), req.method, req.url);
+	return stepModule.default(req);
+}
+
+//#endregion
+export { handler as default };

package/dist/domains/evals/routes/datasetTriggers.d.ts

@@ -1,7 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
-import * as hono7 from "hono";
+import * as hono12 from "hono";
 
 //#region src/domains/evals/routes/datasetTriggers.d.ts
-declare const app: OpenAPIHono<hono7.Env, {}, "/">;
+declare const app: OpenAPIHono<hono12.Env, {}, "/">;
 //#endregion
 export { app as default };

package/dist/domains/evals/routes/index.d.ts

@@ -1,7 +1,7 @@
 import { OpenAPIHono } from "@hono/zod-openapi";
-import * as hono1 from "hono";
+import * as hono13 from "hono";
 
 //#region src/domains/evals/routes/index.d.ts
-declare const app: OpenAPIHono<hono1.Env, {}, "/">;
+declare const app: OpenAPIHono<hono13.Env, {}, "/">;
 //#endregion
 export { app as default };

package/dist/domains/evals/scripts/build-workflow.js

@@ -5,7 +5,7 @@ import { StandaloneBuilder } from "@workflow/builders";
 * Custom workflow build script that supports externalizing native modules.
 *
 * The default `workflow build` CLI doesn't expose the externalPackages option,
-* so we use the builder directly to exclude native modules like keytar.
+* so we use the builder directly to exclude native modules like @napi-rs/keyring.
 */
 const config = {
 	dirs: ["./src/domains/evals/workflow"],
@@ -14,7 +14,7 @@ const config = {
 	stepsBundlePath: "./.well-known/workflow/v1/step.cjs",
 	workflowsBundlePath: "./.well-known/workflow/v1/flow.cjs",
 	webhookBundlePath: "./.well-known/workflow/v1/webhook.mjs",
-	externalPackages: ["keytar"]
+	externalPackages: ["@napi-rs/keyring"]
 };
 async function build() {
 	console.log("Building workflow bundles...");

package/dist/domains/evals/workflow/functions/evaluateConversation.d.ts

@@ -13,7 +13,7 @@ type EvaluationPayload = {
  * - Do NOT call Node.js APIs directly here (no DB, no fs, etc.)
  * - All side effects must happen in step functions
  */
-declare function evaluateConversationWorkflow(payload: EvaluationPayload): Promise<{
+declare function _evaluateConversationWorkflow(payload: EvaluationPayload): Promise<{
   success: boolean;
   reason: string;
   conversationId?: undefined;
@@ -24,5 +24,8 @@ declare function evaluateConversationWorkflow(payload: EvaluationPayload): Promi
   resultCount: number;
   reason?: undefined;
 }>;
+declare const evaluateConversationWorkflow: typeof _evaluateConversationWorkflow & {
+  workflowId: string;
+};
 //#endregion
 export { evaluateConversationWorkflow };

package/dist/domains/evals/workflow/functions/evaluateConversation.js

@@ -102,7 +102,7 @@ async function logStep(message, data) {
 * - Do NOT call Node.js APIs directly here (no DB, no fs, etc.)
 * - All side effects must happen in step functions
 */
-async function evaluateConversationWorkflow(payload) {
+async function _evaluateConversationWorkflow(payload) {
 	"use workflow";
 	const { conversationId, evaluatorIds } = payload;
 	await logStep("Starting conversation evaluation", payload);
@@ -129,6 +129,7 @@ async function evaluateConversationWorkflow(payload) {
 		resultCount: results.length
 	};
 }
+const evaluateConversationWorkflow = Object.assign(_evaluateConversationWorkflow, { workflowId: "workflow//src/domains/evals/workflow/functions/evaluateConversation.ts//_evaluateConversationWorkflow" });
 
 //#endregion
 export { evaluateConversationWorkflow };

package/dist/domains/evals/workflow/functions/runDatasetItem.d.ts

@@ -25,12 +25,15 @@ type RunDatasetItemPayload = {
  * Main workflow function - processes a single dataset item through the chat API.
  * Optionally runs evaluators on the resulting conversation.
  */
-declare function runDatasetItemWorkflow(payload: RunDatasetItemPayload): Promise<{
+declare function _runDatasetItemWorkflow(payload: RunDatasetItemPayload): Promise<{
   success: boolean;
   datasetItemId: string;
   datasetRunId: string;
   conversationId: string | null;
   error: string | null;
 }>;
+declare const runDatasetItemWorkflow: typeof _runDatasetItemWorkflow & {
+  workflowId: string;
+};
 //#endregion
 export { runDatasetItemWorkflow };

package/dist/domains/evals/workflow/functions/runDatasetItem.js

@@ -173,7 +173,7 @@ async function logStep(message, data) {
 * Main workflow function - processes a single dataset item through the chat API.
 * Optionally runs evaluators on the resulting conversation.
 */
-async function runDatasetItemWorkflow(payload) {
+async function _runDatasetItemWorkflow(payload) {
 	"use workflow";
 	const { datasetItemId, datasetRunId, agentId, evaluatorIds, evaluationRunId } = payload;
 	await logStep("Starting dataset item processing", {
@@ -199,6 +199,7 @@ async function runDatasetItemWorkflow(payload) {
 		error: result.error || null
 	};
 }
+const runDatasetItemWorkflow = Object.assign(_runDatasetItemWorkflow, { workflowId: "workflow//src/domains/evals/workflow/functions/runDatasetItem.ts//_runDatasetItemWorkflow" });
 
 //#endregion
 export { runDatasetItemWorkflow };

package/dist/domains/evals/workflow/routes.d.ts

@@ -1,7 +1,7 @@
 import { Hono } from "hono";
-import * as hono_types1 from "hono/types";
+import * as hono_types9 from "hono/types";
 
 //#region src/domains/evals/workflow/routes.d.ts
-declare const workflowRoutes: Hono<hono_types1.BlankEnv, hono_types1.BlankSchema, "/">;
+declare const workflowRoutes: Hono<hono_types9.BlankEnv, hono_types9.BlankSchema, "/">;
 //#endregion
 export { workflowRoutes };

package/dist/domains/evals/workflow/world.js

@@ -11,8 +11,9 @@ import { createVercelWorld } from "@workflow/world-vercel";
 * Vercel's NFT can't trace dynamic imports in bundled code.
 *
 * Set WORKFLOW_TARGET_WORLD to: 'local' | 'vercel' | '@workflow/world-postgres'
+* Defaults to 'local' for development if not set.
 */
-const targetWorld = env.WORKFLOW_TARGET_WORLD;
+const targetWorld = env.WORKFLOW_TARGET_WORLD || "local";
 let world;
 if (targetWorld === "vercel") {
 	const token = process.env.WORKFLOW_VERCEL_AUTH_TOKEN;
@@ -30,7 +31,7 @@ if (targetWorld === "vercel") {
 	jobPrefix: env.WORKFLOW_POSTGRES_JOB_PREFIX,
 	queueConcurrency: Number(env.WORKFLOW_POSTGRES_WORKER_CONCURRENCY) || 10
 });
-else if (targetWorld === "local") world = createLocalWorld();
+else world = createLocalWorld();
 
 //#endregion
 export { world };

package/dist/domains/github/config.d.ts

@@ -0,0 +1,14 @@
+import { z } from "@hono/zod-openapi";
+
+//#region src/domains/github/config.d.ts
+declare const GitHubAppConfigSchema: z.ZodObject<{
+  appId: z.ZodString;
+  privateKey: z.ZodString;
+}, z.core.$strip>;
+type GitHubAppConfig = z.infer<typeof GitHubAppConfigSchema>;
+declare function getGitHubAppConfig(): GitHubAppConfig;
+declare function isGitHubAppConfigured(): boolean;
+declare function validateGitHubAppConfigOnStartup(): void;
+declare function clearConfigCache(): void;
+//#endregion
+export { GitHubAppConfig, clearConfigCache, getGitHubAppConfig, isGitHubAppConfigured, validateGitHubAppConfigOnStartup };

package/dist/domains/github/config.js

@@ -0,0 +1,47 @@
+import { getLogger } from "../../logger.js";
+import { z } from "@hono/zod-openapi";
+
+//#region src/domains/github/config.ts
+const logger = getLogger("github-config");
+const GitHubAppConfigSchema = z.object({
+	appId: z.string().min(1, "GITHUB_APP_ID is required"),
+	privateKey: z.string().min(1, "GITHUB_APP_PRIVATE_KEY is required")
+});
+let cachedConfig = null;
+function getGitHubAppConfig() {
+	if (cachedConfig) return cachedConfig;
+	const appId = process.env.GITHUB_APP_ID;
+	const privateKey = process.env.GITHUB_APP_PRIVATE_KEY?.replace(/\\n/g, "\n");
+	const result = GitHubAppConfigSchema.safeParse({
+		appId,
+		privateKey
+	});
+	if (!result.success) {
+		const errorMessage = `GitHub App credentials are not configured. ${result.error.issues.map((issue) => issue.message).join(". ")}. Please set GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY environment variables.`;
+		logger.error({}, errorMessage);
+		throw new Error(errorMessage);
+	}
+	cachedConfig = result.data;
+	logger.info({}, "GitHub App credentials loaded successfully");
+	return cachedConfig;
+}
+function isGitHubAppConfigured() {
+	return Boolean(process.env.GITHUB_APP_ID && process.env.GITHUB_APP_PRIVATE_KEY);
+}
+function validateGitHubAppConfigOnStartup() {
+	if (!isGitHubAppConfigured()) {
+		logger.warn({}, "GitHub App credentials not configured. Token exchange endpoint will return 500 errors. Set GITHUB_APP_ID and GITHUB_APP_PRIVATE_KEY to enable the feature.");
+		return;
+	}
+	try {
+		getGitHubAppConfig();
+	} catch (error) {
+		logger.error({ error }, "GitHub App credentials are invalid. Token exchange endpoint will return 500 errors.");
+	}
+}
+function clearConfigCache() {
+	cachedConfig = null;
+}
+
+//#endregion
+export { clearConfigCache, getGitHubAppConfig, isGitHubAppConfigured, validateGitHubAppConfigOnStartup };

package/dist/domains/github/index.d.ts

@@ -0,0 +1,12 @@
+import { GitHubAppConfig, getGitHubAppConfig, isGitHubAppConfigured } from "./config.js";
+import { GenerateInstallationAccessTokenResult, GenerateTokenError, GenerateTokenResult, InstallationAccessToken, InstallationInfo, LookupInstallationError, LookupInstallationForRepoResult, LookupInstallationResult, generateInstallationAccessToken, lookupInstallationForRepo } from "./installation.js";
+import { GetJwkResult, JwksError, JwksResult, clearJwksCache, getJwkForToken, getJwksCacheStatus } from "./jwks.js";
+import { GitHubOidcClaims, ValidateOidcTokenResult, ValidateTokenError, ValidateTokenResult, validateOidcToken } from "./oidcToken.js";
+import { Hono } from "hono";
+import * as hono_types5 from "hono/types";
+
+//#region src/domains/github/index.d.ts
+declare function createGithubRoutes(): Hono<hono_types5.BlankEnv, hono_types5.BlankSchema, "/">;
+declare const githubRoutes: Hono<hono_types5.BlankEnv, hono_types5.BlankSchema, "/">;
+//#endregion
+export { type GenerateInstallationAccessTokenResult, type GenerateTokenError, type GenerateTokenResult, type GetJwkResult, type GitHubAppConfig, type GitHubOidcClaims, type InstallationAccessToken, type InstallationInfo, type JwksError, type JwksResult, type LookupInstallationError, type LookupInstallationForRepoResult, type LookupInstallationResult, type ValidateOidcTokenResult, type ValidateTokenError, type ValidateTokenResult, clearJwksCache, createGithubRoutes, generateInstallationAccessToken, getGitHubAppConfig, getJwkForToken, getJwksCacheStatus, githubRoutes, isGitHubAppConfigured, lookupInstallationForRepo, validateOidcToken };

package/dist/domains/github/index.js

@@ -0,0 +1,18 @@
+import { getGitHubAppConfig, isGitHubAppConfigured, validateGitHubAppConfigOnStartup } from "./config.js";
+import { generateInstallationAccessToken, lookupInstallationForRepo } from "./installation.js";
+import { clearJwksCache, getJwkForToken, getJwksCacheStatus } from "./jwks.js";
+import { validateOidcToken } from "./oidcToken.js";
+import tokenExchange_default from "./routes/tokenExchange.js";
+import { Hono } from "hono";
+
+//#region src/domains/github/index.ts
+function createGithubRoutes() {
+	validateGitHubAppConfigOnStartup();
+	const app = new Hono();
+	app.route("/token-exchange", tokenExchange_default);
+	return app;
+}
+const githubRoutes = createGithubRoutes();
+
+//#endregion
+export { clearJwksCache, createGithubRoutes, generateInstallationAccessToken, getGitHubAppConfig, getJwkForToken, getJwksCacheStatus, githubRoutes, isGitHubAppConfigured, lookupInstallationForRepo, validateOidcToken };

package/dist/domains/github/installation.d.ts

@@ -0,0 +1,34 @@
+//#region src/domains/github/installation.d.ts
+interface InstallationInfo {
+  installationId: number;
+  accountLogin: string;
+  accountType: 'User' | 'Organization';
+}
+interface LookupInstallationResult {
+  success: true;
+  installation: InstallationInfo;
+}
+interface LookupInstallationError {
+  success: false;
+  errorType: 'not_installed' | 'api_error' | 'jwt_error';
+  message: string;
+}
+type LookupInstallationForRepoResult = LookupInstallationResult | LookupInstallationError;
+interface InstallationAccessToken {
+  token: string;
+  expiresAt: string;
+}
+interface GenerateTokenResult {
+  success: true;
+  accessToken: InstallationAccessToken;
+}
+interface GenerateTokenError {
+  success: false;
+  errorType: 'api_error' | 'jwt_error';
+  message: string;
+}
+type GenerateInstallationAccessTokenResult = GenerateTokenResult | GenerateTokenError;
+declare function lookupInstallationForRepo(repositoryOwner: string, repositoryName: string): Promise<LookupInstallationForRepoResult>;
+declare function generateInstallationAccessToken(installationId: number): Promise<GenerateInstallationAccessTokenResult>;
+//#endregion
+export { GenerateInstallationAccessTokenResult, GenerateTokenError, GenerateTokenResult, InstallationAccessToken, InstallationInfo, LookupInstallationError, LookupInstallationForRepoResult, LookupInstallationResult, generateInstallationAccessToken, lookupInstallationForRepo };

package/dist/domains/github/installation.js

@@ -0,0 +1,172 @@
+import { getLogger } from "../../logger.js";
+import { getGitHubAppConfig } from "./config.js";
+import { createPrivateKey } from "node:crypto";
+import { SignJWT } from "jose";
+
+//#region src/domains/github/installation.ts
+const logger = getLogger("github-installation");
+const GITHUB_API_BASE = "https://api.github.com";
+async function createAppJwt() {
+	const config = getGitHubAppConfig();
+	const privateKey = createPrivateKey({
+		key: config.privateKey,
+		format: "pem"
+	});
+	const now = Math.floor(Date.now() / 1e3);
+	return await new SignJWT({}).setProtectedHeader({ alg: "RS256" }).setIssuedAt(now - 60).setExpirationTime(now + 600).setIssuer(config.appId).sign(privateKey);
+}
+async function lookupInstallationForRepo(repositoryOwner, repositoryName) {
+	let appJwt;
+	try {
+		appJwt = await createAppJwt();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		logger.error({ error: message }, "Failed to create GitHub App JWT");
+		return {
+			success: false,
+			errorType: "jwt_error",
+			message: `Failed to create GitHub App authentication: ${message}`
+		};
+	}
+	const url = `${GITHUB_API_BASE}/repos/${repositoryOwner}/${repositoryName}/installation`;
+	try {
+		const response = await fetch(url, {
+			method: "GET",
+			headers: {
+				Authorization: `Bearer ${appJwt}`,
+				Accept: "application/vnd.github+json",
+				"X-GitHub-Api-Version": "2022-11-28",
+				"User-Agent": "inkeep-agents-api"
+			}
+		});
+		if (response.status === 404) return {
+			success: false,
+			errorType: "not_installed",
+			message: `GitHub App is not installed on repository ${repositoryOwner}/${repositoryName}. Please install the Inkeep Agents GitHub App on the repository to enable token exchange.`
+		};
+		if (!response.ok) {
+			const errorText = await response.text();
+			logger.error({
+				status: response.status,
+				error: errorText,
+				repositoryOwner,
+				repositoryName
+			}, "GitHub API error looking up installation");
+			return {
+				success: false,
+				errorType: "api_error",
+				message: `GitHub API error (${response.status}): Failed to look up installation for repository`
+			};
+		}
+		const data = await response.json();
+		const installationId = data.id;
+		const accountLogin = data.account?.login;
+		const accountType = data.account?.type;
+		if (typeof installationId !== "number" || typeof accountLogin !== "string") {
+			logger.error({ data }, "Unexpected response format from GitHub API");
+			return {
+				success: false,
+				errorType: "api_error",
+				message: "Unexpected response format from GitHub API"
+			};
+		}
+		logger.info({
+			installationId,
+			accountLogin,
+			accountType,
+			repositoryOwner,
+			repositoryName
+		}, "Found GitHub App installation for repository");
+		return {
+			success: true,
+			installation: {
+				installationId,
+				accountLogin,
+				accountType: accountType === "Organization" ? "Organization" : "User"
+			}
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		logger.error({
+			error: message,
+			repositoryOwner,
+			repositoryName
+		}, "Error calling GitHub API to look up installation");
+		return {
+			success: false,
+			errorType: "api_error",
+			message: `Failed to connect to GitHub API: ${message}`
+		};
+	}
+}
+async function generateInstallationAccessToken(installationId) {
+	let appJwt;
+	try {
+		appJwt = await createAppJwt();
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		logger.error({ error: message }, "Failed to create GitHub App JWT for token generation");
+		return {
+			success: false,
+			errorType: "jwt_error",
+			message: `Failed to create GitHub App authentication: ${message}`
+		};
+	}
+	const url = `${GITHUB_API_BASE}/app/installations/${installationId}/access_tokens`;
+	try {
+		const response = await fetch(url, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${appJwt}`,
+				Accept: "application/vnd.github+json",
+				"X-GitHub-Api-Version": "2022-11-28",
+				"User-Agent": "inkeep-agents-api"
+			}
+		});
+		if (!response.ok) {
+			const errorText = await response.text();
+			logger.error({
+				status: response.status,
+				error: errorText,
+				installationId
+			}, "GitHub API error generating installation access token");
+			return {
+				success: false,
+				errorType: "api_error",
+				message: `GitHub API error (${response.status}): Failed to generate installation access token`
+			};
+		}
+		const data = await response.json();
+		const token = data.token;
+		const expiresAt = data.expires_at;
+		if (typeof token !== "string" || typeof expiresAt !== "string") {
+			logger.error({ data }, "Unexpected response format from GitHub API for token generation");
+			return {
+				success: false,
+				errorType: "api_error",
+				message: "Unexpected response format from GitHub API"
+			};
+		}
+		return {
+			success: true,
+			accessToken: {
+				token,
+				expiresAt
+			}
+		};
+	} catch (error) {
+		const message = error instanceof Error ? error.message : "Unknown error";
+		logger.error({
+			error: message,
+			installationId
+		}, "Error calling GitHub API to generate installation access token");
+		return {
+			success: false,
+			errorType: "api_error",
+			message: `Failed to connect to GitHub API: ${message}`
+		};
+	}
+}
+
+//#endregion
+export { generateInstallationAccessToken, lookupInstallationForRepo };

package/dist/domains/github/jwks.d.ts

@@ -0,0 +1,20 @@
+import { CryptoKey, JWSHeaderParameters } from "jose";
+
+//#region src/domains/github/jwks.d.ts
+interface JwksResult {
+  success: true;
+  key: CryptoKey;
+}
+interface JwksError {
+  success: false;
+  error: string;
+}
+type GetJwkResult = JwksResult | JwksError;
+declare function getJwkForToken(header: JWSHeaderParameters): Promise<GetJwkResult>;
+declare function clearJwksCache(): void;
+declare function getJwksCacheStatus(): {
+  cached: boolean;
+  expiresIn?: number;
+};
+//#endregion
+export { GetJwkResult, JwksError, JwksResult, clearJwksCache, getJwkForToken, getJwksCacheStatus };