@inkeep/agents-work-apps 0.0.0-dev-20260203033642

package/LICENSE.md

@@ -0,0 +1,49 @@
+# Inkeep SDK – Elastic License 2.0 with Supplemental Terms
+
+NOTE: The Inkeep SDK is licensed under the Elastic License 2.0 (ELv2), subject to Supplemental Terms included in [SUPPLEMENTAL_TERMS.md](SUPPLEMENTAL_TERMS.md). In the event of conflict, the Supplemental Terms control.
+
+# Elastic License 2.0
+
+## Acceptance  
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below.
+
+## Limitations
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+## Patents
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Notices
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+## No Other Rights
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+## Termination
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+## No Liability
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+The **licensor** is the entity offering these terms, and the **software** is the software the licensor makes available under these terms, including any portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+

package/dist/db/index.d.ts

@@ -0,0 +1,2 @@
+import runDbClient from "./runDbClient.js";
+export { runDbClient };

package/dist/db/index.js

@@ -0,0 +1,3 @@
+import runDbClient_default from "./runDbClient.js";
+
+export { runDbClient_default as runDbClient };

package/dist/db/runDbClient.d.ts

@@ -0,0 +1,6 @@
+import * as _inkeep_agents_core0 from "@inkeep/agents-core";
+
+//#region src/db/runDbClient.d.ts
+declare const runDbClient: _inkeep_agents_core0.AgentsRunDatabaseClient;
+//#endregion
+export { runDbClient as default };

package/dist/db/runDbClient.js

@@ -0,0 +1,9 @@
+import { env } from "../env.js";
+import { createAgentsRunDatabaseClient } from "@inkeep/agents-core";
+
+//#region src/db/runDbClient.ts
+const runDbClient = createAgentsRunDatabaseClient({ connectionString: env.INKEEP_AGENTS_RUN_DATABASE_URL });
+var runDbClient_default = runDbClient;
+
+//#endregion
+export { runDbClient_default as default };

package/dist/env.d.ts

@@ -0,0 +1,47 @@
+import { z } from "@hono/zod-openapi";
+
+//#region src/env.d.ts
+declare const envSchema: z.ZodObject<{
+  NODE_ENV: z.ZodDefault<z.ZodEnum<{
+    development: "development";
+    production: "production";
+    test: "test";
+  }>>;
+  ENVIRONMENT: z.ZodDefault<z.ZodEnum<{
+    development: "development";
+    production: "production";
+    test: "test";
+    pentest: "pentest";
+  }>>;
+  LOG_LEVEL: z.ZodDefault<z.ZodEnum<{
+    error: "error";
+    trace: "trace";
+    debug: "debug";
+    info: "info";
+    warn: "warn";
+  }>>;
+  INKEEP_AGENTS_RUN_DATABASE_URL: z.ZodString;
+  INKEEP_AGENTS_MANAGE_UI_URL: z.ZodOptional<z.ZodString>;
+  GITHUB_APP_ID: z.ZodOptional<z.ZodString>;
+  GITHUB_APP_PRIVATE_KEY: z.ZodOptional<z.ZodString>;
+  GITHUB_WEBHOOK_SECRET: z.ZodOptional<z.ZodString>;
+  GITHUB_STATE_SIGNING_SECRET: z.ZodOptional<z.ZodString>;
+  GITHUB_APP_NAME: z.ZodOptional<z.ZodString>;
+  GITHUB_MCP_API_KEY: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+declare const env: {
+  NODE_ENV: "development" | "production" | "test";
+  ENVIRONMENT: "development" | "production" | "test" | "pentest";
+  LOG_LEVEL: "error" | "trace" | "debug" | "info" | "warn";
+  INKEEP_AGENTS_RUN_DATABASE_URL: string;
+  INKEEP_AGENTS_MANAGE_UI_URL?: string | undefined;
+  GITHUB_APP_ID?: string | undefined;
+  GITHUB_APP_PRIVATE_KEY?: string | undefined;
+  GITHUB_WEBHOOK_SECRET?: string | undefined;
+  GITHUB_STATE_SIGNING_SECRET?: string | undefined;
+  GITHUB_APP_NAME?: string | undefined;
+  GITHUB_MCP_API_KEY?: string | undefined;
+};
+type Env = z.infer<typeof envSchema>;
+//#endregion
+export { Env, env };

package/dist/env.js

@@ -0,0 +1,48 @@
+import { z } from "@hono/zod-openapi";
+import { loadEnvironmentFiles } from "@inkeep/agents-core";
+
+//#region src/env.ts
+loadEnvironmentFiles();
+const envSchema = z.object({
+	NODE_ENV: z.enum([
+		"development",
+		"production",
+		"test"
+	]).default("development").describe("Node.js environment mode"),
+	ENVIRONMENT: z.enum([
+		"development",
+		"production",
+		"pentest",
+		"test"
+	]).default("development").describe("Application environment mode"),
+	LOG_LEVEL: z.enum([
+		"trace",
+		"debug",
+		"info",
+		"warn",
+		"error"
+	]).default("info").describe("Logging verbosity level"),
+	INKEEP_AGENTS_RUN_DATABASE_URL: z.string().describe("PostgreSQL connection URL for the runtime database (Doltgres with Git version control)"),
+	INKEEP_AGENTS_MANAGE_UI_URL: z.string().optional().describe("URL where the management UI is hosted"),
+	GITHUB_APP_ID: z.string().optional().describe("GitHub App ID for GitHub integration"),
+	GITHUB_APP_PRIVATE_KEY: z.string().optional().describe("GitHub App private key for authentication"),
+	GITHUB_WEBHOOK_SECRET: z.string().optional().describe("Secret for validating GitHub webhook payloads"),
+	GITHUB_STATE_SIGNING_SECRET: z.string().min(32, "GITHUB_STATE_SIGNING_SECRET must be at least 32 characters").optional().describe("Secret for signing GitHub OAuth state (minimum 32 characters)"),
+	GITHUB_APP_NAME: z.string().optional().describe("Name of the GitHub App"),
+	GITHUB_MCP_API_KEY: z.string().optional().describe("API key for the GitHub MCP")
+});
+const parseEnv = () => {
+	try {
+		return envSchema.parse(process.env);
+	} catch (error) {
+		if (error instanceof z.ZodError) {
+			const missingVars = error.issues.map((issue) => issue.path.join("."));
+			throw new Error(`❌ Invalid environment variables: ${missingVars.join(", ")}\n${error.message}`);
+		}
+		throw error;
+	}
+};
+const env = parseEnv();
+
+//#endregion
+export { env };

package/dist/github/config.d.ts

@@ -0,0 +1,22 @@
+import { z } from "@hono/zod-openapi";
+
+//#region src/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;
+declare function isWebhookConfigured(): boolean;
+declare function getWebhookSecret(): string;
+declare function validateGitHubWebhookConfigOnStartup(): void;
+declare function isStateSigningConfigured(): boolean;
+declare function getStateSigningSecret(): string;
+declare function isGitHubAppNameConfigured(): boolean;
+declare function getGitHubAppName(): string;
+declare function validateGitHubInstallFlowConfigOnStartup(): void;
+//#endregion
+export { GitHubAppConfig, clearConfigCache, getGitHubAppConfig, getGitHubAppName, getStateSigningSecret, getWebhookSecret, isGitHubAppConfigured, isGitHubAppNameConfigured, isStateSigningConfigured, isWebhookConfigured, validateGitHubAppConfigOnStartup, validateGitHubInstallFlowConfigOnStartup, validateGitHubWebhookConfigOnStartup };

package/dist/github/config.js

@@ -0,0 +1,79 @@
+import { env } from "../env.js";
+import { getLogger } from "../logger.js";
+import { z } from "@hono/zod-openapi";
+
+//#region src/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 = env.GITHUB_APP_ID;
+	const privateKey = 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({ appId: cachedConfig.appId }, "GitHub App credentials loaded successfully");
+	return cachedConfig;
+}
+function isGitHubAppConfigured() {
+	return Boolean(env.GITHUB_APP_ID && 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;
+}
+function isWebhookConfigured() {
+	return Boolean(env.GITHUB_WEBHOOK_SECRET);
+}
+function getWebhookSecret() {
+	const secret = env.GITHUB_WEBHOOK_SECRET;
+	if (!secret) throw new Error("GITHUB_WEBHOOK_SECRET is not configured");
+	return secret;
+}
+function validateGitHubWebhookConfigOnStartup() {
+	if (!isWebhookConfigured()) logger.warn({}, "GitHub webhook secret not configured. Webhook endpoints will reject all requests. Set GITHUB_WEBHOOK_SECRET to enable webhook processing.");
+}
+function isStateSigningConfigured() {
+	return Boolean(env.GITHUB_STATE_SIGNING_SECRET);
+}
+function getStateSigningSecret() {
+	const secret = env.GITHUB_STATE_SIGNING_SECRET;
+	if (!secret) throw new Error("GITHUB_STATE_SIGNING_SECRET is not configured");
+	return secret;
+}
+function isGitHubAppNameConfigured() {
+	return Boolean(env.GITHUB_APP_NAME);
+}
+function getGitHubAppName() {
+	const appName = env.GITHUB_APP_NAME;
+	if (!appName) throw new Error("GITHUB_APP_NAME is not configured");
+	return appName;
+}
+function validateGitHubInstallFlowConfigOnStartup() {
+	if (!isStateSigningConfigured()) logger.warn({}, "GitHub state signing secret not configured. Install URL endpoint will return 500 errors. Set GITHUB_STATE_SIGNING_SECRET to enable the installation flow.");
+	if (!isGitHubAppNameConfigured()) logger.warn({}, "GitHub App name not configured. Install URL endpoint will return 500 errors. Set GITHUB_APP_NAME to enable the installation flow.");
+}
+
+//#endregion
+export { clearConfigCache, getGitHubAppConfig, getGitHubAppName, getStateSigningSecret, getWebhookSecret, isGitHubAppConfigured, isGitHubAppNameConfigured, isStateSigningConfigured, isWebhookConfigured, validateGitHubAppConfigOnStartup, validateGitHubInstallFlowConfigOnStartup, validateGitHubWebhookConfigOnStartup };

package/dist/github/index.d.ts

@@ -0,0 +1,13 @@
+import { GitHubAppConfig, clearConfigCache, getGitHubAppConfig, getGitHubAppName, getStateSigningSecret, getWebhookSecret, isGitHubAppConfigured, isGitHubAppNameConfigured, isStateSigningConfigured, isWebhookConfigured, validateGitHubAppConfigOnStartup, validateGitHubInstallFlowConfigOnStartup, validateGitHubWebhookConfigOnStartup } from "./config.js";
+import { GenerateInstallationAccessTokenResult, GenerateTokenError, GenerateTokenResult, InstallationAccessToken, InstallationInfo, LookupInstallationError, LookupInstallationForRepoResult, LookupInstallationResult, createAppJwt, determineStatus, fetchInstallationDetails, fetchInstallationRepositories, generateInstallationAccessToken, lookupInstallationForRepo } from "./installation.js";
+import "./routes/setup.js";
+import "./routes/tokenExchange.js";
+import { WebhookVerificationResult, verifyWebhookSignature } from "./routes/webhooks.js";
+import { Hono } from "hono";
+import * as hono_types6 from "hono/types";
+
+//#region src/github/index.d.ts
+declare function createGithubRoutes(): Hono<hono_types6.BlankEnv, hono_types6.BlankSchema, "/">;
+declare const githubRoutes: Hono<hono_types6.BlankEnv, hono_types6.BlankSchema, "/">;
+//#endregion
+export { GenerateInstallationAccessTokenResult, GenerateTokenError, GenerateTokenResult, GitHubAppConfig, InstallationAccessToken, InstallationInfo, LookupInstallationError, LookupInstallationForRepoResult, LookupInstallationResult, WebhookVerificationResult, clearConfigCache, createAppJwt, createGithubRoutes, determineStatus, fetchInstallationDetails, fetchInstallationRepositories, generateInstallationAccessToken, getGitHubAppConfig, getGitHubAppName, getStateSigningSecret, getWebhookSecret, githubRoutes, isGitHubAppConfigured, isGitHubAppNameConfigured, isStateSigningConfigured, isWebhookConfigured, lookupInstallationForRepo, validateGitHubAppConfigOnStartup, validateGitHubInstallFlowConfigOnStartup, validateGitHubWebhookConfigOnStartup, verifyWebhookSignature };

package/dist/github/index.js

@@ -0,0 +1,23 @@
+import { clearConfigCache, getGitHubAppConfig, getGitHubAppName, getStateSigningSecret, getWebhookSecret, isGitHubAppConfigured, isGitHubAppNameConfigured, isStateSigningConfigured, isWebhookConfigured, validateGitHubAppConfigOnStartup, validateGitHubInstallFlowConfigOnStartup, validateGitHubWebhookConfigOnStartup } from "./config.js";
+import mcp_default from "./mcp/index.js";
+import { createAppJwt, determineStatus, fetchInstallationDetails, fetchInstallationRepositories, generateInstallationAccessToken, lookupInstallationForRepo } from "./installation.js";
+import setup_default from "./routes/setup.js";
+import tokenExchange_default from "./routes/tokenExchange.js";
+import webhooks_default, { verifyWebhookSignature } from "./routes/webhooks.js";
+import { Hono } from "hono";
+
+//#region src/github/index.ts
+function createGithubRoutes() {
+	validateGitHubAppConfigOnStartup();
+	validateGitHubWebhookConfigOnStartup();
+	const app = new Hono();
+	app.route("/token-exchange", tokenExchange_default);
+	app.route("/setup", setup_default);
+	app.route("/webhooks", webhooks_default);
+	app.route("/mcp", mcp_default);
+	return app;
+}
+const githubRoutes = createGithubRoutes();
+
+//#endregion
+export { clearConfigCache, createAppJwt, createGithubRoutes, determineStatus, fetchInstallationDetails, fetchInstallationRepositories, generateInstallationAccessToken, getGitHubAppConfig, getGitHubAppName, getStateSigningSecret, getWebhookSecret, githubRoutes, isGitHubAppConfigured, isGitHubAppNameConfigured, isStateSigningConfigured, isWebhookConfigured, lookupInstallationForRepo, validateGitHubAppConfigOnStartup, validateGitHubInstallFlowConfigOnStartup, validateGitHubWebhookConfigOnStartup, verifyWebhookSignature };

package/dist/github/installation.d.ts

@@ -0,0 +1,66 @@
+//#region src/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 SetupAction = 'install' | 'update' | 'request';
+interface GitHubInstallationResponse {
+  id: number;
+  account: {
+    login: string;
+    id: number;
+    type: 'Organization' | 'User';
+  };
+}
+interface GitHubRepository {
+  id: number;
+  name: string;
+  full_name: string;
+  private: boolean;
+}
+type GenerateInstallationAccessTokenResult = GenerateTokenResult | GenerateTokenError;
+declare function createAppJwt(): Promise<string>;
+declare function lookupInstallationForRepo(repositoryOwner: string, repositoryName: string): Promise<LookupInstallationForRepoResult>;
+declare function generateInstallationAccessToken(installationId: number): Promise<GenerateInstallationAccessTokenResult>;
+declare function fetchInstallationDetails(installationId: string, appJwt: string): Promise<{
+  success: true;
+  installation: GitHubInstallationResponse;
+} | {
+  success: false;
+  error: string;
+  status: number;
+}>;
+declare function fetchInstallationRepositories(installationId: string, appJwt: string): Promise<{
+  success: true;
+  repositories: GitHubRepository[];
+} | {
+  success: false;
+  error: string;
+}>;
+declare function determineStatus(setupAction: SetupAction): 'active' | 'pending';
+//#endregion
+export { GenerateInstallationAccessTokenResult, GenerateTokenError, GenerateTokenResult, InstallationAccessToken, InstallationInfo, LookupInstallationError, LookupInstallationForRepoResult, LookupInstallationResult, createAppJwt, determineStatus, fetchInstallationDetails, fetchInstallationRepositories, generateInstallationAccessToken, lookupInstallationForRepo };

package/dist/github/installation.js

@@ -0,0 +1,293 @@
+import { getLogger } from "../logger.js";
+import { getGitHubAppConfig } from "./config.js";
+import { SignJWT } from "jose";
+import { createPrivateKey } from "node:crypto";
+
+//#region src/github/installation.ts
+const logger = getLogger("github-installation");
+const GITHUB_API_BASE = "https://api.github.com";
+async function createAppJwt() {
+	const config = getGitHubAppConfig();
+	logger.debug({ appId: config.appId }, "Creating GitHub App JWT");
+	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}`
+		};
+	}
+}
+async function fetchInstallationDetails(installationId, appJwt) {
+	const url = `${GITHUB_API_BASE}/app/installations/${installationId}`;
+	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.ok) {
+			const errorText = await response.text();
+			logger.error({
+				status: response.status,
+				error: errorText,
+				installationId
+			}, "Failed to fetch installation details");
+			return {
+				success: false,
+				error: `GitHub API error: ${response.status}`,
+				status: response.status
+			};
+		}
+		return {
+			success: true,
+			installation: await response.json()
+		};
+	} catch (error) {
+		logger.error({
+			error,
+			installationId
+		}, "Error fetching installation details");
+		return {
+			success: false,
+			error: "Failed to connect to GitHub API",
+			status: 500
+		};
+	}
+}
+async function fetchInstallationRepositories(installationId, appJwt) {
+	const tokenUrl = `${GITHUB_API_BASE}/app/installations/${installationId}/access_tokens`;
+	try {
+		const tokenResponse = await fetch(tokenUrl, {
+			method: "POST",
+			headers: {
+				Authorization: `Bearer ${appJwt}`,
+				Accept: "application/vnd.github+json",
+				"X-GitHub-Api-Version": "2022-11-28",
+				"User-Agent": "inkeep-agents-api"
+			}
+		});
+		if (!tokenResponse.ok) {
+			const errorText = await tokenResponse.text();
+			logger.error({
+				status: tokenResponse.status,
+				error: errorText,
+				installationId
+			}, "Failed to get installation access token");
+			return {
+				success: false,
+				error: "Failed to get installation access token"
+			};
+		}
+		const installationToken = (await tokenResponse.json()).token;
+		const allRepositories = [];
+		let page = 1;
+		const perPage = 100;
+		while (true) {
+			const reposUrl = `${GITHUB_API_BASE}/installation/repositories?per_page=${perPage}&page=${page}`;
+			const reposResponse = await fetch(reposUrl, {
+				method: "GET",
+				headers: {
+					Authorization: `Bearer ${installationToken}`,
+					Accept: "application/vnd.github+json",
+					"X-GitHub-Api-Version": "2022-11-28",
+					"User-Agent": "inkeep-agents-api"
+				}
+			});
+			if (!reposResponse.ok) {
+				const errorText = await reposResponse.text();
+				logger.error({
+					status: reposResponse.status,
+					error: errorText,
+					installationId
+				}, "Failed to fetch repositories");
+				return {
+					success: false,
+					error: "Failed to fetch repositories"
+				};
+			}
+			const reposData = await reposResponse.json();
+			allRepositories.push(...reposData.repositories);
+			if (reposData.repositories.length < perPage) break;
+			page++;
+		}
+		return {
+			success: true,
+			repositories: allRepositories
+		};
+	} catch (error) {
+		logger.error({
+			error,
+			installationId
+		}, "Error fetching installation repositories");
+		return {
+			success: false,
+			error: "Failed to connect to GitHub API"
+		};
+	}
+}
+function determineStatus(setupAction) {
+	switch (setupAction) {
+		case "install":
+		case "update": return "active";
+		case "request": return "pending";
+		default: return "active";
+	}
+}
+
+//#endregion
+export { createAppJwt, determineStatus, fetchInstallationDetails, fetchInstallationRepositories, generateInstallationAccessToken, lookupInstallationForRepo };