@inkeep/agents-manage-api 0.39.4 → 0.40.0

package/dist/middleware/require-permission.js

@@ -0,0 +1,80 @@
+import { env } from "../env.js";
+import { createApiError } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/require-permission.ts
+function formatPermissionsForDisplay(permissions) {
+	const formatted = [];
+	for (const [resource, actions] of Object.entries(permissions)) {
+		const actionList = Array.isArray(actions) ? actions : [actions];
+		for (const action of actionList) formatted.push(`${resource}:${action}`);
+	}
+	return formatted;
+}
+const requirePermission = (permissions) => createMiddleware(async (c, next) => {
+	const isTestEnvironment = process.env.ENVIRONMENT === "test";
+	const auth = c.get("auth");
+	if (env.DISABLE_AUTH || isTestEnvironment || !auth) {
+		await next();
+		return;
+	}
+	const userId = c.get("userId");
+	const tenantId = c.get("tenantId");
+	const tenantRole = c.get("tenantRole");
+	const requiredPermissions = formatPermissionsForDisplay(permissions);
+	if (userId === "system" || userId?.startsWith("apikey:")) {
+		await next();
+		return;
+	}
+	if (!userId || !tenantId) throw createApiError({
+		code: "unauthorized",
+		message: "User or organization context not found. Ensure you are authenticated and belong to an organization.",
+		instance: c.req.path,
+		extensions: {
+			requiredPermissions,
+			context: {
+				hasUserId: !!userId,
+				hasTenantId: !!tenantId
+			}
+		}
+	});
+	try {
+		const result = await auth.api.hasPermission({
+			body: {
+				permissions,
+				organizationId: tenantId
+			},
+			headers: c.req.raw.headers
+		});
+		if (!result || !result.success) throw createApiError({
+			code: "forbidden",
+			message: `Permission denied. Required: ${requiredPermissions.join(", ")}`,
+			instance: c.req.path,
+			extensions: {
+				requiredPermissions,
+				context: {
+					userId,
+					organizationId: tenantId,
+					currentRole: tenantRole || "unknown"
+				}
+			}
+		});
+		await next();
+	} catch (error) {
+		if (error instanceof HTTPException) throw error;
+		const errorMessage = error instanceof Error ? error.message : "Unknown error";
+		throw createApiError({
+			code: "internal_server_error",
+			message: "Failed to verify permissions",
+			instance: c.req.path,
+			extensions: {
+				requiredPermissions,
+				internalError: errorMessage
+			}
+		});
+	}
+});
+
+//#endregion
+export { requirePermission };

package/dist/middleware/session-auth.d.ts

@@ -0,0 +1,6 @@
+import * as hono0 from "hono";
+
+//#region src/middleware/session-auth.d.ts
+declare const sessionAuth: () => hono0.MiddlewareHandler<any, string, {}, Response>;
+//#endregion
+export { sessionAuth };

package/dist/middleware/session-auth.js

@@ -0,0 +1,26 @@
+import { createApiError } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/session-auth.ts
+const sessionAuth = () => createMiddleware(async (c, next) => {
+	try {
+		const user = c.get("user");
+		if (!user) throw createApiError({
+			code: "unauthorized",
+			message: "Please log in to access this resource"
+		});
+		c.set("userId", user.id);
+		c.set("userEmail", user.email);
+		await next();
+	} catch (error) {
+		if (error instanceof HTTPException) throw error;
+		throw createApiError({
+			code: "unauthorized",
+			message: "Authentication failed"
+		});
+	}
+});
+
+//#endregion
+export { sessionAuth };

package/dist/middleware/tenant-access.d.ts

@@ -0,0 +1,12 @@
+import * as hono0 from "hono";
+
+//#region src/middleware/tenant-access.d.ts
+declare const requireTenantAccess: () => hono0.MiddlewareHandler<{
+  Variables: {
+    userId: string;
+    tenantId: string;
+    tenantRole: string;
+  };
+}, string, {}, Response>;
+//#endregion
+export { requireTenantAccess };

package/dist/middleware/tenant-access.js

@@ -0,0 +1,54 @@
+import dbClient_default from "../data/db/dbClient.js";
+import { createApiError, getUserOrganizations } from "@inkeep/agents-core";
+import { createMiddleware } from "hono/factory";
+import { HTTPException } from "hono/http-exception";
+
+//#region src/middleware/tenant-access.ts
+const requireTenantAccess = () => createMiddleware(async (c, next) => {
+	const userId = c.get("userId");
+	const tenantId = c.req.param("tenantId");
+	if (!userId) throw createApiError({
+		code: "unauthorized",
+		message: "User ID not found"
+	});
+	if (!tenantId) throw createApiError({
+		code: "bad_request",
+		message: "Organization ID is required"
+	});
+	if (userId === "system") {
+		c.set("tenantId", tenantId);
+		c.set("tenantRole", "owner");
+		await next();
+		return;
+	}
+	if (userId.startsWith("apikey:")) {
+		const apiKeyTenantId = c.get("tenantId");
+		if (apiKeyTenantId && apiKeyTenantId !== tenantId) throw createApiError({
+			code: "forbidden",
+			message: "API key does not have access to this organization"
+		});
+		c.set("tenantId", tenantId);
+		c.set("tenantRole", "owner");
+		await next();
+		return;
+	}
+	try {
+		const organizationAccess = (await getUserOrganizations(dbClient_default)(userId)).find((org) => org.organizationId === tenantId);
+		if (!organizationAccess) throw createApiError({
+			code: "forbidden",
+			message: "Access denied to this organization"
+		});
+		c.set("tenantId", tenantId);
+		c.set("tenantRole", organizationAccess.role);
+		await next();
+	} catch (error) {
+		if (error instanceof HTTPException) throw error;
+		throw createApiError({
+			code: "internal_server_error",
+			message: "Failed to verify organization access"
+		});
+	}
+});
+
+//#endregion
+export { requireTenantAccess };

package/dist/openapi.d.ts

@@ -0,0 +1,7 @@
+import { OpenAPIHono } from "@hono/zod-openapi";
+import { Env } from "hono";
+
+//#region src/openapi.d.ts
+declare function setupOpenAPIRoutes<E extends Env = Env>(app: OpenAPIHono<E>): void;
+//#endregion
+export { setupOpenAPIRoutes };

package/dist/openapi.js

@@ -0,0 +1,157 @@
+import { env } from "./env.js";
+import { swaggerUI } from "@hono/swagger-ui";
+
+//#region src/openapi.ts
+function setupOpenAPIRoutes(app) {
+	app.get("/openapi.json", (c) => {
+		try {
+			const serverUrl = process.env.VERCEL_ENV === "production" && process.env.VERCEL_PROJECT_PRODUCTION_URL ? `https://${process.env.VERCEL_PROJECT_PRODUCTION_URL}` : process.env.VERCEL_ENV === "preview" && process.env.VERCEL_URL ? `https://${process.env.VERCEL_URL}` : env.INKEEP_AGENTS_MANAGE_API_URL;
+			const document = app.getOpenAPIDocument({
+				openapi: "3.0.0",
+				info: {
+					title: "Inkeep Agents Manage API",
+					version: "1.0.0",
+					description: "REST API for the management of the Inkeep Agent Framework."
+				},
+				servers: [{
+					url: serverUrl,
+					description: "API Server"
+				}],
+				tags: [
+					{
+						name: "Agent",
+						description: "Operations for managing individual agents"
+					},
+					{
+						name: "Agent Artifact Component Relations",
+						description: "Operations for managing agent artifact component relationships"
+					},
+					{
+						name: "Agent Data Component Relations",
+						description: "Operations for managing agent data component relationships"
+					},
+					{
+						name: "Agents",
+						description: "Operations for managing agents"
+					},
+					{
+						name: "API Keys",
+						description: "Operations for managing API keys"
+					},
+					{
+						name: "Artifact Component",
+						description: "Operations for managing artifact components"
+					},
+					{
+						name: "Context Config",
+						description: "Operations for managing context configurations"
+					},
+					{
+						name: "Credential",
+						description: "Operations for managing credentials"
+					},
+					{
+						name: "Credential Store",
+						description: "Operations for managing credential stores"
+					},
+					{
+						name: "Data Component",
+						description: "Operations for managing data components"
+					},
+					{
+						name: "External Agents",
+						description: "Operations for managing external agents"
+					},
+					{
+						name: "Full Agent",
+						description: "Operations for managing complete agent definitions"
+					},
+					{
+						name: "Full Project",
+						description: "Operations for managing complete project definitions"
+					},
+					{
+						name: "Function Tools",
+						description: "Operations for managing function tools"
+					},
+					{
+						name: "Functions",
+						description: "Operations for managing functions"
+					},
+					{
+						name: "OAuth",
+						description: "OAuth authentication endpoints for MCP tools"
+					},
+					{
+						name: "Projects",
+						description: "Operations for managing projects"
+					},
+					{
+						name: "Sub Agent External Agent Relations",
+						description: "Operations for managing sub agent external agent relationships"
+					},
+					{
+						name: "Sub Agent Relations",
+						description: "Operations for managing sub agent relationships"
+					},
+					{
+						name: "Sub Agent Team Agent Relations",
+						description: "Operations for managing sub agent team agent relationships"
+					},
+					{
+						name: "SubAgent",
+						description: "Operations for managing sub agents"
+					},
+					{
+						name: "SubAgent Tool Relations",
+						description: "Operations for managing sub agent tool relationships"
+					},
+					{
+						name: "Tools",
+						description: "Operations for managing MCP tools"
+					}
+				]
+			});
+			document.components = {
+				...document.components,
+				securitySchemes: {
+					...document.components?.securitySchemes || {},
+					cookieAuth: {
+						type: "apiKey",
+						in: "cookie",
+						name: "better-auth.session_token",
+						description: "Session-based authentication using HTTP-only cookies. Cookies are automatically sent by browsers. For server-side requests, include cookies with names starting with \"better-auth.\" in the Cookie header."
+					},
+					bearerAuth: {
+						type: "http",
+						scheme: "bearer",
+						bearerFormat: "Token",
+						description: "Bearer token authentication. Use this for API clients and service-to-service communication. Set the Authorization header to \"Bearer <token>\"."
+					}
+				}
+			};
+			document.security = [{
+				cookieAuth: [],
+				bearerAuth: []
+			}];
+			return c.json(document);
+		} catch (error) {
+			console.error("OpenAPI document generation failed:", error);
+			const errorDetails = error instanceof Error ? {
+				message: error.message,
+				stack: error.stack
+			} : JSON.stringify(error, null, 2);
+			return c.json({
+				error: "Failed to generate OpenAPI document",
+				details: errorDetails
+			}, 500);
+		}
+	});
+	app.get("/docs", swaggerUI({
+		url: "/openapi.json",
+		title: "Inkeep Agents Manage API Documentation"
+	}));
+}
+
+//#endregion
+export { setupOpenAPIRoutes };

package/dist/routes/agent.d.ts

@@ -0,0 +1,9 @@
+import { BaseAppVariables } from "../types/app.js";
+import { OpenAPIHono } from "@hono/zod-openapi";
+
+//#region src/routes/agent.d.ts
+declare const app: OpenAPIHono<{
+  Variables: BaseAppVariables;
+}, {}, "/">;
+//#endregion
+export { app as default };

package/dist/routes/agent.js

@@ -0,0 +1,244 @@
+import dbClient_default from "../data/db/dbClient.js";
+import { requirePermission } from "../middleware/require-permission.js";
+import { speakeasyOffsetLimitPagination } from "./shared.js";
+import { OpenAPIHono, createRoute } from "@hono/zod-openapi";
+import { AgentApiInsertSchema, AgentApiUpdateSchema, AgentListResponse, AgentResponse, AgentWithinContextOfProjectResponse, ErrorResponseSchema, PaginationQueryParamsSchema, RelatedAgentInfoListResponse, TenantProjectAgentParamsSchema, TenantProjectAgentSubAgentParamsSchema, TenantProjectIdParamsSchema, TenantProjectParamsSchema, commonGetErrorResponses, createAgent, createApiError, deleteAgent, generateId, getAgentById, getAgentSubAgentInfos, getFullAgentDefinition, listAgentsPaginated, updateAgent } from "@inkeep/agents-core";
+
+//#region src/routes/agent.ts
+const app = new OpenAPIHono();
+app.use("/", async (c, next) => {
+	if (c.req.method === "POST") return requirePermission({ agent: ["create"] })(c, next);
+	return next();
+});
+app.use("/:id", async (c, next) => {
+	if (c.req.method === "PUT") return requirePermission({ agent: ["update"] })(c, next);
+	if (c.req.method === "DELETE") return requirePermission({ agent: ["delete"] })(c, next);
+	return next();
+});
+app.openapi(createRoute({
+	method: "get",
+	path: "/",
+	summary: "List Agents",
+	operationId: "list-agents",
+	tags: ["Agents"],
+	request: {
+		params: TenantProjectParamsSchema,
+		query: PaginationQueryParamsSchema
+	},
+	responses: {
+		200: {
+			description: "List of agents retrieved successfully",
+			content: { "application/json": { schema: AgentListResponse } }
+		},
+		...commonGetErrorResponses
+	},
+	...speakeasyOffsetLimitPagination
+}), async (c) => {
+	const { tenantId, projectId } = c.req.valid("param");
+	const page = Number(c.req.query("page")) || 1;
+	const limit = Math.min(Number(c.req.query("limit")) || 10, 100);
+	const result = await listAgentsPaginated(dbClient_default)({
+		scopes: {
+			tenantId,
+			projectId
+		},
+		pagination: {
+			page,
+			limit
+		}
+	});
+	return c.json(result);
+});
+app.openapi(createRoute({
+	method: "get",
+	path: "/{id}",
+	summary: "Get Agent",
+	operationId: "get-agent",
+	tags: ["Agents"],
+	request: { params: TenantProjectIdParamsSchema },
+	responses: {
+		200: {
+			description: "Agent found",
+			content: { "application/json": { schema: AgentResponse } }
+		},
+		...commonGetErrorResponses
+	}
+}), async (c) => {
+	const { tenantId, projectId, id } = c.req.valid("param");
+	const agent = await getAgentById(dbClient_default)({ scopes: {
+		tenantId,
+		projectId,
+		agentId: id
+	} });
+	if (!agent) throw createApiError({
+		code: "not_found",
+		message: "Agent not found"
+	});
+	return c.json({ data: agent });
+});
+app.openapi(createRoute({
+	method: "get",
+	path: "/{agentId}/sub-agents/{subAgentId}/related",
+	summary: "Get Related Agent Infos",
+	operationId: "get-related-agent-infos",
+	tags: ["Agent"],
+	request: { params: TenantProjectAgentSubAgentParamsSchema },
+	responses: {
+		200: {
+			description: "Related agent infos retrieved successfully",
+			content: { "application/json": { schema: RelatedAgentInfoListResponse } }
+		},
+		...commonGetErrorResponses
+	}
+}), async (c) => {
+	const { tenantId, projectId, agentId, subAgentId } = c.req.valid("param");
+	const relatedAgents = await getAgentSubAgentInfos(dbClient_default)({
+		scopes: {
+			tenantId,
+			projectId
+		},
+		agentId,
+		subAgentId
+	});
+	return c.json({
+		data: relatedAgents,
+		pagination: {
+			page: 1,
+			limit: relatedAgents.length,
+			total: relatedAgents.length,
+			pages: 1
+		}
+	});
+});
+app.openapi(createRoute({
+	method: "get",
+	path: "/{agentId}/full",
+	summary: "Get Full Agent Definition",
+	operationId: "get-full-agent-definition",
+	tags: ["Agent"],
+	request: { params: TenantProjectAgentParamsSchema },
+	responses: {
+		200: {
+			description: "Full agent definition retrieved successfully",
+			content: { "application/json": { schema: AgentWithinContextOfProjectResponse } }
+		},
+		...commonGetErrorResponses
+	}
+}), async (c) => {
+	const { tenantId, projectId, agentId } = c.req.valid("param");
+	const fullAgent = await getFullAgentDefinition(dbClient_default)({ scopes: {
+		tenantId,
+		projectId,
+		agentId
+	} });
+	if (!fullAgent) throw createApiError({
+		code: "not_found",
+		message: "Agent not found"
+	});
+	return c.json({ data: fullAgent });
+});
+app.openapi(createRoute({
+	method: "post",
+	path: "/",
+	summary: "Create Agent",
+	operationId: "create-agent",
+	tags: ["Agents"],
+	request: {
+		params: TenantProjectParamsSchema,
+		body: { content: { "application/json": { schema: AgentApiInsertSchema } } }
+	},
+	responses: {
+		201: {
+			description: "Agent created successfully",
+			content: { "application/json": { schema: AgentResponse } }
+		},
+		...commonGetErrorResponses
+	}
+}), async (c) => {
+	const { tenantId, projectId } = c.req.valid("param");
+	const validatedBody = c.req.valid("json");
+	try {
+		const agent = await createAgent(dbClient_default)({
+			tenantId,
+			projectId,
+			id: validatedBody.id || generateId(),
+			name: validatedBody.name,
+			defaultSubAgentId: validatedBody.defaultSubAgentId,
+			contextConfigId: validatedBody.contextConfigId ?? void 0
+		});
+		return c.json({ data: agent }, 201);
+	} catch (error) {
+		if (error?.cause?.code === "23505") throw createApiError({
+			code: "conflict",
+			message: `An agent with ID '${validatedBody.id || "unknown"}' already exists`
+		});
+		throw error;
+	}
+});
+app.openapi(createRoute({
+	method: "put",
+	path: "/{id}",
+	summary: "Update Agent",
+	operationId: "update-agent",
+	tags: ["Agents"],
+	request: {
+		params: TenantProjectIdParamsSchema,
+		body: { content: { "application/json": { schema: AgentApiUpdateSchema } } }
+	},
+	responses: {
+		200: {
+			description: "Agent updated successfully",
+			content: { "application/json": { schema: AgentResponse } }
+		},
+		...commonGetErrorResponses
+	}
+}), async (c) => {
+	const { tenantId, projectId, id } = c.req.valid("param");
+	const validatedBody = c.req.valid("json");
+	const updatedAgent = await updateAgent(dbClient_default)({
+		scopes: {
+			tenantId,
+			projectId,
+			agentId: id
+		},
+		data: {
+			defaultSubAgentId: validatedBody.defaultSubAgentId,
+			contextConfigId: validatedBody.contextConfigId ?? void 0
+		}
+	});
+	if (!updatedAgent) throw createApiError({
+		code: "not_found",
+		message: "Agent not found"
+	});
+	return c.json({ data: updatedAgent });
+});
+app.openapi(createRoute({
+	method: "delete",
+	path: "/{id}",
+	summary: "Delete Agent",
+	operationId: "delete-agent",
+	tags: ["Agents"],
+	request: { params: TenantProjectIdParamsSchema },
+	responses: {
+		204: { description: "Agent deleted successfully" },
+		404: {
+			description: "Agent not found",
+			content: { "application/json": { schema: ErrorResponseSchema } }
+		}
+	}
+}), async (c) => {
+	const { tenantId, projectId, id } = c.req.valid("param");
+	if (!await deleteAgent(dbClient_default)({ scopes: {
+		tenantId,
+		projectId,
+		agentId: id
+	} })) throw createApiError({
+		code: "not_found",
+		message: "Agent not found"
+	});
+	return c.body(null, 204);
+});
+var agent_default = app;
+
+//#endregion
+export { agent_default as default };

package/dist/routes/agentFull.d.ts

@@ -0,0 +1,9 @@
+import { BaseAppVariables } from "../types/app.js";
+import { OpenAPIHono } from "@hono/zod-openapi";
+
+//#region src/routes/agentFull.d.ts
+declare const app: OpenAPIHono<{
+  Variables: BaseAppVariables;
+}, {}, "/">;
+//#endregion
+export { app as default };