The open-source app everyone uses to manage agents at work
TypeScript acpxagent-orchestrationagent-skillsagentic-aiai-agentsai-engineeringai-governanceai-toolsautonomous-agentsclaudeclaude-codeclaude-skillscodexhermesllmmcpmulti-agentopenclawproject-managementworkflow-automation
import { parseRemoteHttpEndpoint } from "../remote-http-endpoint-guard.js";
import type { AppDefinition, ConnectionMethodDef, ToolConnectionTransport } from "@paperclipai/shared";
import {
credentialConfigPath,
getAvailableConnectionMethod,
getAvailableConnectionMethods,
getConnectableAppDefinition,
resolveConnectionMethodServerUrl,
checkMcpRemoteHeaderName,
checkMcpRemoteHeaderValue,
mcpRemoteHeaderRejectionMessage,
} from "@paperclipai/shared";
import { badRequest, unprocessable } from "../../errors.js";
import { isPaperclipCloudConnectorStrategy } from "../paperclip-cloud-connector.js";
import { honchoManagedArguments } from "../honcho-connection.js";
import { assertGoogleChatToolArgumentsSupported, googleChatToolInputSchema } from "../google-chat-tool-policy.js";
import { gmailArchiveToolInputSchema } from "../gmail-archive-tool-policy.js";
type ConnectionSettings = {
config: Record<string, unknown>;
transport: ToolConnectionTransport;
transportConfig?: Record<string, unknown>;
};
function asRecord(value: unknown): Record<string, unknown> {
if (value && typeof value === "object" && !Array.isArray(value))
return value as Record<string, unknown>;
return {};
}
export function connectionMethodFor(app: AppDefinition, methodKey?: string | null) {
const normalizedMethodKey =
app.slug === "gmail" && methodKey === "paperclip-id-oauth"
? "paperclip-draft"
: methodKey;
// Stored managed connections must remain recognizable for callback, refresh,
// and revoke even though static definitions omit instance availability. New
// setup passes a definition filtered by signed profiles before reaching here;
// the broker independently enforces availability on authorization and refresh.
const availableMethods = new Set(getAvailableConnectionMethods(app));
const toolMethods = app.methods.filter(
(candidate) =>
candidate.purpose !== "channel" && candidate.purpose !== "ai"
&& candidate.transport !== "chat_sdk" && candidate.transport !== "runtime_auth"
&& (availableMethods.has(candidate) || isPaperclipCloudConnectorStrategy(candidate.oauthStrategy)),
);
const method = normalizedMethodKey
? (toolMethods.find((candidate) => candidate.key === normalizedMethodKey) ??
null)
: getAvailableConnectionMethod({ ...app, methods: toolMethods }, null);
if (!method)
throw unprocessable(
"This app does not have an available connection method",
);
return method;
}
export function connectionMethodForConnection(
app: AppDefinition,
connection: ConnectionSettings,
) {
const methodKey =
typeof connection.config.connectionMethodKey === "string"
? connection.config.connectionMethodKey
: null;
return connectionMethodFor(app, methodKey);
}
export function credentialFieldsFor(app: AppDefinition, methodKey?: string | null) {
const method = connectionMethodFor(app, methodKey);
return (method.credentialFields ?? []).map((field) => ({
label: field.label,
configPath: credentialConfigPath(field, method),
helpUrl: method.consoleLinks?.keys ?? method.consoleLinks?.docs ?? "",
required: field.required,
placement:
method.keyPlacement?.location === "header"
? ("header" as const)
: undefined,
key: method.keyPlacement?.name,
prefix: method.keyPlacement?.prefix,
}));
}
export function normalizeConnectionMethodConfig(
method: ConnectionMethodDef,
configValues: Record<string, unknown> | undefined,
): {
values: Record<string, string | boolean>;
url?: string;
headers?: Record<string, string>;
} {
const fields = [
...(method.tenantFields ?? []),
...(method.extensionFields ?? []),
];
const allowedKeys = new Set(fields.map((field) => field.key));
for (const key of Object.keys(configValues ?? {})) {
if (!allowedKeys.has(key))
throw badRequest(`Unknown connection setting: ${key}`);
}
const values: Record<string, string | boolean> = {};
for (const field of fields) {
const raw = configValues?.[field.key] ?? field.defaultValue;
if (field.type === "checkbox") {
if (raw !== undefined && typeof raw !== "boolean")
throw badRequest(`${field.label} must be true or false`);
if (raw !== undefined) values[field.key] = raw;
continue;
}
if (raw !== undefined && typeof raw !== "string")
throw badRequest(`${field.label} must be text`);
let value = raw?.trim() ?? "";
if (field.transport?.format === "csv") {
value = Array.from(
new Set(
value
.split(/[\n,]/g)
.map((entry) => entry.trim())
.filter(Boolean),
),
).join(",");
}
if (field.required && !value)
throw badRequest(`Missing connection setting: ${field.label}`);
if (!value) continue;
if (
field.validation?.maxLength &&
value.length > field.validation.maxLength
) {
throw badRequest(
`${field.label} must be at most ${field.validation.maxLength} characters`,
);
}
if (
field.validation?.pattern &&
!new RegExp(field.validation.pattern).test(value)
) {
throw badRequest(`${field.label} has an invalid value`);
}
if (
field.type === "select" &&
!field.options?.some((option) => option.value === value)
) {
throw badRequest(`${field.label} has an invalid option`);
}
values[field.key] = value;
}
for (const keys of method.configRequirements?.atLeastOneOf
? [method.configRequirements.atLeastOneOf]
: []) {
if (
!keys.some(
(key) => typeof values[key] === "string" && values[key].length > 0,
)
) {
throw badRequest(`Provide at least one of: ${keys.join(", ")}`);
}
}
const resolvedServerUrl = resolveConnectionMethodServerUrl(method, values);
if (method.defaults?.serverUrlTemplate && !resolvedServerUrl) {
throw badRequest(
"Missing or invalid connection settings for the server URL",
);
}
const endpoint = resolvedServerUrl ? new URL(resolvedServerUrl) : null;
if (endpoint && endpoint.protocol !== "https:") {
throw badRequest("Connection server URL must use HTTPS");
}
const headers: Record<string, string> = {};
for (const field of fields) {
const transport = field.transport;
const value = values[field.key];
if (
!transport ||
value === undefined ||
(value === false && transport.omitFalse)
)
continue;
const serialized = typeof value === "boolean" ? String(value) : value;
if (transport.location === "query")
endpoint?.searchParams.set(transport.name, serialized);
else {
const nameCheck = checkMcpRemoteHeaderName(transport.name);
const valueCheck = checkMcpRemoteHeaderValue(serialized);
if (!nameCheck.ok || !valueCheck.ok) {
throw badRequest(
mcpRemoteHeaderRejectionMessage(
transport.name,
nameCheck.reason ?? valueCheck.reason!,
),
);
}
headers[transport.name] = serialized;
}
}
return {
values,
...(endpoint ? { url: endpoint.toString() } : {}),
...(Object.keys(headers).length > 0 ? { headers } : {}),
};
}
export function projectedConnectionHeaders(
connection: ConnectionSettings,
): Record<string, string> {
const sourceTemplateKey =
typeof connection.config.sourceTemplateKey === "string"
? connection.config.sourceTemplateKey
: null;
const app = sourceTemplateKey
? getConnectableAppDefinition(sourceTemplateKey)
: null;
const headers: Record<string, string> = {};
if (app) {
const method = connectionMethodForConnection(app, connection);
// Non-transport settings do not participate in header projection. In
// particular, legacy connections can lack a newly introduced setting.
if ([...(method.tenantFields ?? []), ...(method.extensionFields ?? [])].some((field) => field.transport?.location === "header")) {
Object.assign(headers, normalizeConnectionMethodConfig(
method,
asRecord(connection.config.methodConfig),
).headers);
}
}
if (
connection.transport === "mcp_remote" &&
(sourceTemplateKey === "github" || connection.transportConfig?.sourceTemplateKey === "github")
) {
// GitHub excludes Actions from its default catalog. Project this on every
// discovery and invocation so existing connections gain the toolset too.
headers["X-MCP-Toolsets"] = "default,actions";
}
return headers;
}
function mergeManagedToolArguments(
supplied: Record<string, unknown>,
managed: Record<string, unknown>,
): Record<string, unknown> {
const merged = { ...supplied };
for (const [key, value] of Object.entries(managed)) {
const suppliedValue = merged[key];
merged[key] =
asRecord(value) === value && asRecord(suppliedValue) === suppliedValue
? mergeManagedToolArguments(
suppliedValue as Record<string, unknown>,
value as Record<string, unknown>,
)
: value;
}
return merged;
}
export function projectConnectionMethodToolArguments(
method: ConnectionMethodDef,
parameters: unknown,
): Record<string, unknown> {
const supplied = asRecord(parameters);
const managed = method.defaults?.toolArgumentDefaults;
return managed ? mergeManagedToolArguments(supplied, managed) : supplied;
}
function stripManagedToolArgumentSchema(
schema: Record<string, unknown>,
managed: Record<string, unknown>,
): Record<string, unknown> {
const properties = asRecord(schema.properties);
if (Object.keys(properties).length === 0) return schema;
const nextProperties = { ...properties };
for (const [key, managedValue] of Object.entries(managed)) {
const propertySchema = asRecord(nextProperties[key]);
const managedRecord = asRecord(managedValue);
if (
Object.keys(propertySchema).length === 0 ||
Object.keys(managedRecord).length === 0
) {
delete nextProperties[key];
continue;
}
const projectedProperty = stripManagedToolArgumentSchema(
propertySchema,
managedRecord,
);
if (Object.keys(asRecord(projectedProperty.properties)).length === 0)
delete nextProperties[key];
else nextProperties[key] = projectedProperty;
}
const nextSchema: Record<string, unknown> = {
...schema,
properties: nextProperties,
};
if (Array.isArray(schema.required)) {
const required = schema.required.filter(
(key): key is string => typeof key === "string" && key in nextProperties,
);
if (required.length > 0) nextSchema.required = required;
else delete nextSchema.required;
}
return nextSchema;
}
export function projectConnectionMethodToolInputSchema(
method: ConnectionMethodDef,
inputSchema: Record<string, unknown>,
): Record<string, unknown> {
const managed = method.defaults?.toolArgumentDefaults;
return managed
? stripManagedToolArgumentSchema(inputSchema, managed)
: inputSchema;
}
export function projectedConnectionToolArguments(
connection: ConnectionSettings,
parameters: unknown,
toolName: string,
inputSchema: Record<string, unknown> = {},
): Record<string, unknown> {
const managed = honchoManagedArguments(connection, inputSchema);
if (managed) parameters = mergeManagedToolArguments(asRecord(parameters), managed);
assertGoogleChatToolArgumentsSupported(connection, toolName, parameters);
const sourceTemplateKey =
typeof connection.config.sourceTemplateKey === "string"
? connection.config.sourceTemplateKey
: null;
const app = sourceTemplateKey
? getConnectableAppDefinition(sourceTemplateKey)
: null;
if (!app) return asRecord(parameters);
return projectConnectionMethodToolArguments(
connectionMethodForConnection(app, connection),
parameters,
);
}
export function projectedConnectionToolInputSchema(
connection: ConnectionSettings,
inputSchema: Record<string, unknown>,
toolName: string,
): Record<string, unknown> {
const managed = honchoManagedArguments(connection, inputSchema);
if (managed) inputSchema = stripManagedToolArgumentSchema(inputSchema, managed);
inputSchema = googleChatToolInputSchema(connection, toolName, inputSchema);
inputSchema = gmailArchiveToolInputSchema(connection, toolName, inputSchema);
const sourceTemplateKey =
typeof connection.config.sourceTemplateKey === "string"
? connection.config.sourceTemplateKey
: null;
const app = sourceTemplateKey
? getConnectableAppDefinition(sourceTemplateKey)
: null;
if (!app) return inputSchema;
return projectConnectionMethodToolInputSchema(
connectionMethodForConnection(app, connection),
inputSchema,
);
}
export function remoteEndpoint(config: Record<string, unknown>): string {
const value = config.url ?? config.endpoint ?? config.remoteUrl;
const parsed = parseRemoteHttpEndpoint(value, (message, code) =>
badRequest(message, { code }),
);
return parsed.toString();
}