mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-20 09:50:48 +01:00
## Thinking Path > - Paperclip is the open source app people use to manage AI agents for work > - The AWS connector (#22195) lets agents use AWS with credentials minted per connection. Its role method stores no AWS keys > - That method needs the customer to create an IAM role that trusts exactly one Paperclip connection, but setup only offered the generic form and a doc > - The connect API also refused the draft step this method needs, so the role method could not be set up through the UI at all > - This pull request adds a guided setup screen. Paperclip saves a draft, hands the user a prompt for their own agent that creates the role, takes back the role ARN the agent reports, and tests the same draft. CloudFormation and IAM steps are there under "Or do it by hand" > - The benefit is that a person can connect AWS without stored keys and without typing account details, using a template AWS has validated ## Linked Issues or Issue Description Refs #22195. **Subsystem affected** Connections (AWS connector setup), UI, tool-access API. **Problem or motivation** The AWS role method must save a connection before AWS can trust it. The API rejected `saveDraft` for every method except custom MCP servers, so the UI could not complete this flow. There was also no screen that showed the issuer, the subject, the trust policy or a template. **Proposed solution** - The connect API accepts `saveDraft` for methods that declare `credentialMinter`. - `GET /tool-connections/:id/aws-setup` returns the setup values and a CloudFormation template generated for that connection. - A new `AwsRoleSetup` step runs between saving the draft and testing it. The role is named after the connection and CloudFormation fills in the account, so the first form no longer asks for a role ARN; the user pastes it back once the role exists. **Alternatives considered** - A one-click CloudFormation quick-create link. Rejected: AWS accepts quick-create templates only from Amazon S3, so Paperclip would need to host a public template bucket. The screen offers a download and a console link instead. - Instructions in a doc only. Rejected: too many hand-copied values. - Asking for the role ARN up front. Rejected: the role does not exist yet, so users had to invent an ARN and then match it exactly. - Letting the user's agent report the role ARN to Paperclip itself, through a short-lived link. Not done here: it needs a new unauthenticated endpoint (and a Paperclip Cloud front-door change). The user pastes the ARN instead. ## What Changed - `packages/shared`: - The `saveDraft` validation allows methods with minted credentials. - New `AwsConnectionSetup` type. - `server/src/services/connectors/aws/setup.ts` builds the setup values: - The issuer, audience and connection subject. - The provider host and the trust policy. - A CloudFormation template with an optional identity provider (`CreateIdentityProvider`), a role named `paperclip-<connection id>`, `AccessPolicyArn` (`ReadOnlyAccess` by default for read-only connections) and `AWSMCPSignInOAuthAccessPolicy`. The account comes from CloudFormation, so the template needs no edits. - The service method `getAwsSetup` and the route `GET /api/tool-connections/{connectionId}/aws-setup`: - The route requires `connections:configure`. - It returns 422 for a connection that is not an AWS role connection. - It reports whether the issuer key is published and any role ARN already saved. - It returns `available: false` (`address_changed`) when the instance address changed after the draft was saved, since a role set up for the old address could never pass the test. - It is registered in OpenAPI. - UI: - The AWS form no longer shows a Role ARN field (it is hidden with an empty default). - `AwsRoleSetup.tsx` shows, by default, only "Set it up with your agent" (a copyable prompt that checks the AWS account, deploys the template with `aws cloudformation deploy`, and reports the role ARN) and a field to paste that ARN. "Or do it by hand" reveals the CloudFormation steps (download, console link, parameter notes, IAM acknowledgement) and the IAM console / AWS CLI steps with copyable values; the CLI commands read the account ID themselves. - It shows an access-key message when AWS cannot reach the instance, and asks the user to save again when the instance address changed. - Failed tests appear in place. AWS error codes show the server's own plain message, because the shared error copy replaces every 502 with "temporarily unavailable". - `useAwsRoleSetupStep` owns the AWS sequence; `ConnectionSetupFlow` only asks it for request options, hands back results and renders its step: - The first Connect for `aws-role` saves a draft and opens the AWS step. - "Test connection" resumes the same draft with the pasted role ARN. - Back keeps the draft, so a later Connect updates it and does not create a second one. Returning to an unfinished draft reopens the step. - Docs: the `doc/connections/AWS.md` setup section and the plan's phase table. The SDK public input pins are refreshed. ## Verification - `server/src/__tests__/aws-mcp-connector.test.ts` covers a new API-level case through the real route validation: - Saving an `aws-role` draft over HTTP works without a role ARN, and stores the keys the screen uses to reopen it. - `aws-setup` returns the issuer, subject and the connection's role name. - The template's trust condition keys equal `<issuer host>:aud` and `<issuer host>:sub`. - The template provider URL equals the issuer. - After an address change it returns `address_changed`, and saving the draft again records the new address. - An access-key connection returns 422. - No response field looks like a secret. - `ui/src/features/connections/AwsRoleSetup.test.tsx` covers: - Only the agent setup shows by default; Test connection stays off until a valid role ARN is pasted, then sends it. - A saved role ARN is filled in. - The by-hand steps and CLI commands; the agent prompt for read-only and full access. - The template download (filename and object URL cleanup). - The unreachable-instance message. - The in-place error and the address-changed message. - The AWS message mapping. - `ui/src/pages/apps/AppsConnect.test.tsx` covers the full two-step flow: the form has no Role ARN field, the first Connect sends `saveDraft: true` with no role ARN and does not finish, the AWS step loads the setup, and "Test connection" resumes `aws-draft` with the pasted role ARN and finishes. A second test reopens the step for a returning draft. - Red/green: - Removing the API change fails the API test. - Removing the draft-first wiring fails the flow test. - Totals: server AWS, OpenAPI and connector tests (75), shared `app-definitions` (42), UI connections and apps pages (1108). Typecheck is clean for shared, server, UI (except Storybook's generated catalog, which this worktree has not built) and all four server test-tree layers. - Browser, on a real dev server with an HTTPS public address: - AWS appears in Connectors with its logo. - The form has only region and access level. Connect saves the draft (reusing an earlier one) and shows only the agent prompt and the role ARN field; "Or do it by hand" reveals the CloudFormation and IAM steps. - The copied prompt names the connection's role and stack, and the template. - Test connection with a pasted role ARN showed AWS's refusal in place (no such role, placeholder issuer), as expected. An earlier run found the generic 502 copy problem, which is fixed and re-checked. - AWS CloudFormation `validate-template` (dev account, read-only) accepts the current generated template (role named after the connection) and reports `CAPABILITY_NAMED_IAM`. The screen tells the user to acknowledge it. - Not run: an agent actually running the prompt and creating a stack in AWS, and Paperclip Cloud staging. ## Risks - The feature is still behind `enableAwsConnector` (off by default). No migration. - The template creates IAM resources in the customer's account, and the customer must acknowledge that. The role trusts only this connection's subject. - If the customer already has an identity provider for the issuer and leaves `CreateIdentityProvider` at true, AWS fails the stack with a clear error. The screen explains the parameter. ## Model Used - Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use (shell, file edits, the in-app browser against a local dev server, AWS CLI `validate-template` in the dev account, an exploration subagent). ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have searched GitHub for duplicate or related PRs and linked them above - [x] I have either (a) linked existing issues with `Fixes: #` / `Closes #` / `Refs #` OR (b) described the issue in-PR following the relevant issue template - [x] I have not referenced internal/instance-local Paperclip issues or links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip` URLs) - [x] My branch name describes the change (e.g. `docs/...`, `fix/...`) and contains no internal Paperclip ticket id or instance-derived details - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [ ] All Paperclip CI gates are green - [ ] Greptile is 5/5 with no open P2s, recommendations, or follow-ups - [x] I will address all Greptile and reviewer comments before requesting merge 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: Paperclip <noreply@paperclip.ing>
656 lines
31 KiB
TypeScript
656 lines
31 KiB
TypeScript
import type { AggregatorAppsResponse, ArcadeDiscoverySetupInput } from "@paperclipai/shared/aggregator-apps";
|
|
import type { ProviderToolIconsResponse } from "@paperclipai/shared";
|
|
import { setPluginAppDefinitions } from "@paperclipai/shared";
|
|
import type { ComposioAppAccountInput, ComposioAppSetupInput, ComposioAppSetupResult, ComposioAppSnapshot, ComposioAppsResponse } from "@paperclipai/shared";
|
|
import type {
|
|
ToolApplication,
|
|
ConfigureRailwaySsh,
|
|
RailwaySshSetup,
|
|
ToolConnection,
|
|
ToolConnectionInstall,
|
|
ToolConnectionInstallSnapshot,
|
|
ToolConnectionRemovalSummary,
|
|
ToolConnectionContentDeletion,
|
|
ToolConnectionStoredContent,
|
|
ConnectToolAppResult,
|
|
ConnectToolApp,
|
|
FinishToolAppResult,
|
|
ToolCatalogEntry,
|
|
ToolRuntimeSlot,
|
|
ToolPolicy,
|
|
ToolConnectionHealthCheckResult,
|
|
ToolCatalogRefreshResult,
|
|
ToolAccessDecision,
|
|
ToolAccessDecisionInput,
|
|
CreateToolPolicy,
|
|
DuplicateToolPolicy,
|
|
McpJsonImportPreview,
|
|
ToolRuntimeHealthSummary,
|
|
ToolRunDecisionLookup,
|
|
ToolOAuthStartResult,
|
|
ToolStdioCommandTemplate,
|
|
ToolProfileBinding,
|
|
ToolProfileBindingTargetType,
|
|
ToolProfileDefaultAction,
|
|
ToolProfileEffectiveSummary,
|
|
ToolProfileEntry,
|
|
ToolProfileEntryEffect,
|
|
ToolProfileEntrySelectorType,
|
|
ToolProfileStatus,
|
|
ToolProfileWithDetails,
|
|
ToolProfileConfiguration,
|
|
ToolProfileNewToolReviewDecision,
|
|
ToolProfileNewToolsReview,
|
|
ToolProfileNewToolsReviewResult,
|
|
ToolRiskLevel,
|
|
UpdateToolPolicy,
|
|
ReorderToolPolicies,
|
|
AppDefinition,
|
|
ToolAppsAttentionResponse,
|
|
ToolConnectionReviewCounts,
|
|
ToolConnectionActivityResponse,
|
|
ToolConnectionLifecycleEventType,
|
|
ToolConnectionTestAgentsResponse,
|
|
ToolConnectionTestAgentAccessResponse,
|
|
ToolConnectionTestCallResult,
|
|
ToolConnectionTestCallStatus,
|
|
ToolActionRequest,
|
|
ToolActionRequestStatus,
|
|
ToolActionRequestsResponse,
|
|
ToolMcpGatewayWithTokens,
|
|
ToolMcpGatewayTokenCreated,
|
|
ToolMcpGatewayToken,
|
|
CreateToolMcpGateway,
|
|
CreateToolMcpGatewayToken,
|
|
UpdateToolMcpGateway,
|
|
CreateToolTrustRuleFromActionRequest,
|
|
ToolRedactedValueSummary,
|
|
ConnectionGrant,
|
|
ConnectionGrantRevocationResult,
|
|
ConnectionGrantKind,
|
|
ConnectionGrantDelegation,
|
|
ConnectionGrantsResponse,
|
|
ToolConnectionCreateCapabilities,
|
|
ToolAppMetadataPreflightResult,
|
|
} from "@paperclipai/shared";
|
|
import { api, detachInflightGet, type RequestOptions } from "./client";
|
|
|
|
/**
|
|
* Tools & Access API client (Phase 6, PAP-10389).
|
|
*
|
|
* Mirrors the governed MCP/tool-access contracts shipped by Phases 2-5
|
|
* (`server/src/routes/tool-access.ts` and `tool-gateway.ts`). The UI consumes
|
|
* server-side enforcement contracts directly instead of faking tool access in
|
|
* the browser.
|
|
*/
|
|
|
|
export type ToolApplicationsResponse = { applications: ToolApplication[] };
|
|
export type ToolConnectionsResponse = { connections: ToolConnection[] };
|
|
export type ToolCatalogResponse = { catalog: ToolCatalogEntry[] };
|
|
export type ToolRuntimeSlotsResponse = { runtimeSlots: ToolRuntimeSlot[] };
|
|
export type ToolRuntimeHealthResponse = ToolRuntimeHealthSummary;
|
|
export type ToolTrustRulesResponse = { trustRules: ToolPolicy[] };
|
|
export type ToolPoliciesResponse = { policies: ToolPolicy[] };
|
|
export type ToolProfilesResponse = { profiles: ToolProfileWithDetails[] };
|
|
export type ToolGalleryResponse = {
|
|
apps: AppDefinition[];
|
|
/** Full definitions of plugin-provided connectors (gallery entries may hide methods). */
|
|
pluginApps?: AppDefinition[];
|
|
/** Server-authoritative OAuth callback URI, omitted when this deployment has no supported browser origin. */
|
|
oauthCallbackUrl?: string;
|
|
capabilities: ToolConnectionCreateCapabilities;
|
|
credentialSources: {
|
|
vercelConnect: {
|
|
available: boolean;
|
|
enabled: boolean;
|
|
authentication: "workload_oidc" | "access_token" | null;
|
|
manageUrl: string;
|
|
reason: string | null;
|
|
};
|
|
};
|
|
};
|
|
export type ToolMcpGatewaysResponse = { gateways: ToolMcpGatewayWithTokens[] };
|
|
export type CloudConnectorEnrollmentStatus = {
|
|
configured: boolean;
|
|
status: "not_configured" | "unenrolled" | "pending" | "active" | "suspended" | "unverified";
|
|
brokerBaseUrl: string;
|
|
instanceId: string | null;
|
|
environment: "development" | "test" | "staging" | "production";
|
|
origins: string[];
|
|
verificationUrl?: string;
|
|
expiresAt?: string;
|
|
};
|
|
export type CreateGatewayTokenInput = Omit<CreateToolMcpGatewayToken, "expiresAt"> & {
|
|
expiresAt?: string | Date | null;
|
|
};
|
|
/** Gateway update payload — `companyId` is injected by the client method. */
|
|
export type UpdateGatewayInput = Omit<UpdateToolMcpGateway, "companyId">;
|
|
export type ReviewNewToolsInput = {
|
|
decisions: Array<{ catalogEntryId: string; decision: ToolProfileNewToolReviewDecision }>;
|
|
};
|
|
|
|
export type StdioTemplateSummary = ToolStdioCommandTemplate;
|
|
export type StdioTemplatesResponse = { templates: StdioTemplateSummary[] };
|
|
|
|
/** Admin "run your own" command-template create input (M8b, PAP-10862). */
|
|
export interface CreateStdioTemplateInput {
|
|
templateId: string;
|
|
name: string;
|
|
description?: string | null;
|
|
command: string;
|
|
args?: string[];
|
|
envKeys?: string[];
|
|
}
|
|
|
|
export interface CreateToolApplicationInput {
|
|
name: string;
|
|
description?: string | null;
|
|
type: ToolApplication["type"];
|
|
pluginId?: string | null;
|
|
metadata?: Record<string, unknown> | null;
|
|
}
|
|
|
|
export interface UpdateToolApplicationInput {
|
|
name?: string;
|
|
description?: string | null;
|
|
status?: ToolApplication["status"];
|
|
metadata?: Record<string, unknown> | null;
|
|
}
|
|
|
|
export interface CreateToolConnectionInput {
|
|
applicationId?: string;
|
|
applicationName?: string;
|
|
name: string;
|
|
transport: NonNullable<ToolConnection["transport"]>;
|
|
status?: ToolConnection["status"];
|
|
config?: Record<string, unknown>;
|
|
credentialRefs?: ToolConnection["credentialRefs"];
|
|
enabled?: boolean;
|
|
}
|
|
|
|
export interface UpdateToolConnectionInput {
|
|
agentInstructions?: import("@paperclipai/shared").ConnectionAgentInstructions | null;
|
|
name?: string;
|
|
status?: ToolConnection["status"];
|
|
config?: Record<string, unknown>;
|
|
transportConfig?: Record<string, unknown>;
|
|
credentialRefs?: ToolConnection["credentialRefs"];
|
|
enabled?: boolean;
|
|
}
|
|
|
|
export interface ToolProfileEntryInput {
|
|
selectorType: ToolProfileEntrySelectorType;
|
|
effect?: ToolProfileEntryEffect;
|
|
applicationId?: string | null;
|
|
connectionId?: string | null;
|
|
catalogEntryId?: string | null;
|
|
toolName?: string | null;
|
|
riskLevel?: ToolRiskLevel | null;
|
|
conditions?: Record<string, unknown> | null;
|
|
}
|
|
|
|
export interface CreateToolProfileInput {
|
|
profileKey: string;
|
|
name: string;
|
|
description?: string | null;
|
|
status?: ToolProfileStatus;
|
|
defaultAction?: ToolProfileDefaultAction;
|
|
metadata?: Record<string, unknown> | null;
|
|
entries?: ToolProfileEntryInput[];
|
|
}
|
|
|
|
export interface UpdateToolProfileInput {
|
|
profileKey?: string;
|
|
name?: string;
|
|
description?: string | null;
|
|
status?: ToolProfileStatus;
|
|
defaultAction?: ToolProfileDefaultAction;
|
|
metadata?: Record<string, unknown> | null;
|
|
entries?: ToolProfileEntryInput[];
|
|
}
|
|
|
|
export interface ToolProfileBindingInput {
|
|
targetType: ToolProfileBindingTargetType;
|
|
targetId: string;
|
|
priority?: number;
|
|
metadata?: Record<string, unknown> | null;
|
|
}
|
|
|
|
export type UnbindToolProfileInput = Pick<ToolProfileBindingInput, "targetType" | "targetId">;
|
|
|
|
/** Redacted tool-gateway audit row (subset of `activity_log`). */
|
|
export interface ToolGatewayAuditRow {
|
|
id: string;
|
|
companyId: string;
|
|
action: string;
|
|
actorType: string | null;
|
|
actorId: string | null;
|
|
entityType: string | null;
|
|
entityId: string | null;
|
|
details: Record<string, unknown> | null;
|
|
createdAt: string;
|
|
}
|
|
|
|
/** Normalized outcome for the humanized Activity feed. */
|
|
export type ToolAuditOutcome =
|
|
| "allowed"
|
|
| "blocked"
|
|
| "asked_first"
|
|
| "waiting"
|
|
| "failed"
|
|
| "unknown";
|
|
|
|
/**
|
|
* Audit row enriched server-side with humanized display names and a normalized
|
|
* outcome — the shape returned by `GET /tool-gateway/audit`.
|
|
*/
|
|
export interface ToolGatewayActivityEvent extends ToolGatewayAuditRow {
|
|
agentId: string | null;
|
|
runId: string | null;
|
|
applicationId: string | null;
|
|
connectionId: string | null;
|
|
agentDisplayName: string | null;
|
|
actorDisplayName?: string | null;
|
|
appDisplayName: string | null;
|
|
applicationDisplayName: string | null;
|
|
connectionDisplayName: string | null;
|
|
toolDisplayName: string | null;
|
|
lifecycleType?: ToolConnectionLifecycleEventType | null;
|
|
normalizedOutcome: ToolAuditOutcome;
|
|
invocation: {
|
|
id: string;
|
|
toolName: string;
|
|
status: string;
|
|
policyDecision: string | null;
|
|
approvalState: string;
|
|
argumentsSummary: ToolRedactedValueSummary | null;
|
|
resultSummary: ToolRedactedValueSummary | null;
|
|
resultSizeBytes: number | null;
|
|
errorCode: string | null;
|
|
errorMessage: string | null;
|
|
startedAt: string | null;
|
|
completedAt: string | null;
|
|
} | null;
|
|
}
|
|
|
|
export type ToolGatewayActivityResponse = {
|
|
events: ToolGatewayActivityEvent[];
|
|
nextCursor: string | null;
|
|
};
|
|
|
|
export type ToolAuditWindow = "1h" | "24h" | "7d" | "30d" | "all";
|
|
|
|
export interface ListActivityParams {
|
|
gateway?: string | null;
|
|
app?: string | null;
|
|
agent?: string | null;
|
|
outcome?: string | null;
|
|
window?: ToolAuditWindow;
|
|
search?: string | null;
|
|
limit?: number;
|
|
cursor?: string | null;
|
|
}
|
|
|
|
export type ToolPolicyTestResponse = {
|
|
decision: ToolAccessDecision;
|
|
auditEvent: unknown | null;
|
|
};
|
|
|
|
export const toolsApi = {
|
|
getCloudConnectorEnrollment: () =>
|
|
api.get<CloudConnectorEnrollmentStatus>("/tools/oauth/cloud-connector/enrollment"),
|
|
startCloudConnectorEnrollment: (companyId: string, label?: string, returnTo?: string) =>
|
|
api.post<CloudConnectorEnrollmentStatus>("/tools/oauth/cloud-connector/enrollment", { companyId, label, returnTo }),
|
|
// --- Applications ---
|
|
listGallery: (companyId: string) =>
|
|
api.get<ToolGalleryResponse>(`/companies/${companyId}/tools/gallery`).then((gallery) => {
|
|
// Plugin-provided connectors are known only from the host. Make them
|
|
// resolvable by the same catalog lookups the setup screens use; apps of
|
|
// a plugin that was disabled since the last response drop out here.
|
|
setPluginAppDefinitions(gallery.pluginApps ?? gallery.apps.filter((app) => app.plugin));
|
|
return gallery;
|
|
}),
|
|
preflightAppMetadata: (companyId: string, galleryKey: string, methodKey?: string | null) => {
|
|
const query = methodKey ? `?methodKey=${encodeURIComponent(methodKey)}` : "";
|
|
return api.get<ToolAppMetadataPreflightResult>(
|
|
`/companies/${companyId}/tools/apps/${encodeURIComponent(galleryKey)}/preflight${query}`,
|
|
);
|
|
},
|
|
connectApp: (companyId: string, input: ConnectToolApp) =>
|
|
api.post<ConnectToolAppResult>(`/companies/${companyId}/tools/apps/connect`, input),
|
|
createMachineSignIn: (companyId: string, input: import("@paperclipai/shared").CreateMachineSignIn) =>
|
|
api.post<import("@paperclipai/shared").MachineSignInSetupResult>(`/companies/${companyId}/tools/machine-sign-in`, input),
|
|
getAwsSetup: (connectionId: string, accessLevel?: "read_only" | "full") =>
|
|
api.get<import("@paperclipai/shared").AwsConnectionSetup>(
|
|
`/tool-connections/${connectionId}/aws-setup${accessLevel ? `?accessLevel=${accessLevel}` : ""}`,
|
|
),
|
|
getMachineSignIn: (connectionId: string) =>
|
|
api.get<import("@paperclipai/shared").MachineSignInStatus>(`/tool-connections/${connectionId}/machine-sign-in`),
|
|
testMachineSignIn: (connectionId: string, input: import("@paperclipai/shared").TestMachineSignIn) =>
|
|
api.post<ConnectToolAppResult>(`/tool-connections/${connectionId}/machine-sign-in/test`, input),
|
|
rotateMachineSignIn: (connectionId: string, input: import("@paperclipai/shared").RotateMachineSignIn) =>
|
|
api.post<import("@paperclipai/shared").MachineSignInSetupResult & { completed: boolean }>(`/tool-connections/${connectionId}/machine-sign-in/rotate`, input),
|
|
completeMachineSignInRotation: (connectionId: string) =>
|
|
api.post<import("@paperclipai/shared").MachineSignInSetupResult>(`/tool-connections/${connectionId}/machine-sign-in/rotate/complete`, {}),
|
|
startOAuth: (
|
|
connectionId: string,
|
|
input: {
|
|
asCurrentUser?: boolean;
|
|
asAgentId?: string;
|
|
interactionId?: string;
|
|
workspaceServices?: import("@paperclipai/shared").GoogleWorkspaceServiceSelection;
|
|
} = {},
|
|
) =>
|
|
api.post<ToolOAuthStartResult>(`/tools/oauth/${connectionId}/start`, input),
|
|
finalizeOAuthAccess: (
|
|
companyId: string,
|
|
connectionId: string,
|
|
input: { grantKind: ConnectionGrantKind },
|
|
) =>
|
|
api.post<FinishToolAppResult>(
|
|
`/companies/${companyId}/tools/apps/${connectionId}/finalize-oauth-access`,
|
|
input,
|
|
),
|
|
finishApp: (companyId: string, connectionId: string, input: {
|
|
enabledCatalogEntryIds: string[];
|
|
askFirstCatalogEntryIds: string[];
|
|
reviewedCatalogEntryIds?: string[];
|
|
agentInstructions?: import("@paperclipai/shared").ConnectionAgentInstructions | null;
|
|
access: "all_agents" | { agentIds: string[] };
|
|
}) =>
|
|
api.post<FinishToolAppResult>(
|
|
`/companies/${companyId}/tools/apps/${connectionId}/finish`,
|
|
input,
|
|
),
|
|
getConnectionReviewCounts: (connectionId: string) =>
|
|
api.get<ToolConnectionReviewCounts>(`/tool-connections/${connectionId}/review-counts`),
|
|
listAppsAttention: (companyId: string) =>
|
|
api.get<ToolAppsAttentionResponse>(`/companies/${companyId}/tools/apps/attention`),
|
|
listApplications: (companyId: string, options?: RequestOptions) =>
|
|
options ? api.get<ToolApplicationsResponse>(`/companies/${companyId}/tools/applications`, options)
|
|
: api.get<ToolApplicationsResponse>(`/companies/${companyId}/tools/applications`),
|
|
createApplication: (companyId: string, input: CreateToolApplicationInput) =>
|
|
api.post<ToolApplication>(`/companies/${companyId}/tools/applications`, input),
|
|
updateApplication: (applicationId: string, input: UpdateToolApplicationInput) =>
|
|
api.patch<ToolApplication>(`/tool-applications/${applicationId}`, input),
|
|
deleteApplication: (applicationId: string) =>
|
|
api.delete<ToolApplication>(`/tool-applications/${applicationId}`),
|
|
|
|
// --- Connections ---
|
|
listConnections: (companyId: string, options?: RequestOptions) =>
|
|
options ? api.get<ToolConnectionsResponse>(`/companies/${companyId}/tools/connections`, options)
|
|
: api.get<ToolConnectionsResponse>(`/companies/${companyId}/tools/connections`),
|
|
getConnection: (connectionId: string, options?: RequestOptions) =>
|
|
api.get<ToolConnection>(`/tool-connections/${connectionId}`, options),
|
|
// --- Installs (Phase 3b, PAP-13618): which agents carry this connection's
|
|
// tools in their runtime context. `installed ⊆ permitted`; the server
|
|
// auto-extends access (adds profile bindings) for any newly-installed target.
|
|
getConnectionInstalls: (connectionId: string, options?: RequestOptions) =>
|
|
api.get<{ connectionId: string; installs: ToolConnectionInstall[] }>(
|
|
`/tool-connections/${connectionId}/installs`, options,
|
|
),
|
|
putConnectionInstalls: (
|
|
connectionId: string,
|
|
installs: Array<{ targetType: "company" | "agent"; targetId: string }>,
|
|
) =>
|
|
api.put<ToolConnectionInstallSnapshot>(
|
|
`/tool-connections/${connectionId}/installs`,
|
|
{ installs },
|
|
),
|
|
// --- Identity grants (PAP-17835): who a connection acts as. The response
|
|
// carries server-computed capabilities and the audience member directory, so
|
|
// the UI never rebuilds the permission matrix from `membershipRole`.
|
|
listConnectionGrants: (connectionId: string, options?: RequestOptions) =>
|
|
api.get<ConnectionGrantsResponse>(`/tool-connections/${connectionId}/grants`, { timeoutMs: 15_000, ...options }),
|
|
createConnectionGrantDelegation: (connectionId: string, grantId: string, agentId: string) =>
|
|
api.post<ConnectionGrantDelegation>(
|
|
`/tool-connections/${connectionId}/grants/${grantId}/delegations`,
|
|
{ agentId },
|
|
),
|
|
revokeConnectionGrantDelegation: (
|
|
connectionId: string,
|
|
grantId: string,
|
|
delegationId: string,
|
|
) => api.delete<ConnectionGrantDelegation>(
|
|
`/tool-connections/${connectionId}/grants/${grantId}/delegations/${delegationId}`,
|
|
),
|
|
revokeConnectionGrant: (connectionId: string, grantId: string) =>
|
|
api.delete<ConnectionGrantRevocationResult>(`/tool-connections/${connectionId}/grants/${grantId}`),
|
|
// An empty `memberUserIds` is the canonical "all organization members".
|
|
// Replacement is atomic server-side, so this never partially widens access.
|
|
replaceConnectionGrantMembers: (connectionId: string, grantId: string, memberUserIds: string[]) =>
|
|
api.put<ConnectionGrant>(
|
|
`/tool-connections/${connectionId}/grants/${grantId}/members`,
|
|
{ memberUserIds },
|
|
),
|
|
/**
|
|
* Start the signed-in user's own personal authorization. `subjectUserId` must
|
|
* be the caller: the server refuses any other subject, so there is no way to
|
|
* initiate consent on someone else's behalf.
|
|
*/
|
|
startPersonalAuthorization: (
|
|
companyId: string,
|
|
connectionId: string,
|
|
input: { subjectUserId: string; scopes?: string[]; returnTo?: string },
|
|
) =>
|
|
api.post<{ url: string; handoff?: ToolOAuthStartResult["handoff"] }>(
|
|
`/companies/${companyId}/tools/connections/${connectionId}/start-authorization`,
|
|
input,
|
|
),
|
|
createConnection: (companyId: string, input: CreateToolConnectionInput) =>
|
|
api.post<ToolConnection>(`/companies/${companyId}/tools/connections`, input),
|
|
updateConnection: (connectionId: string, input: UpdateToolConnectionInput) =>
|
|
api.patch<ToolConnection>(`/tool-connections/${connectionId}`, input),
|
|
configureRailwaySsh: (connectionId: string, input: ConfigureRailwaySsh) =>
|
|
api.post<RailwaySshSetup | null>(`/tool-connections/${connectionId}/railway/ssh`, input),
|
|
// Removal is a credential-revoking teardown (PAP-17119), so the response
|
|
// carries the cleanup receipt alongside the archived connection.
|
|
archiveConnection: (connectionId: string, options: { deleteStoredContent?: boolean } = {}) =>
|
|
api.delete<ToolConnection & { removal: ToolConnectionRemovalSummary; contentDeletion?: ToolConnectionContentDeletion }>(
|
|
`/tool-connections/${connectionId}${options.deleteStoredContent ? "?deleteStoredContent=true" : ""}`,
|
|
),
|
|
getStoredContent: (connectionId: string) =>
|
|
api.get<ToolConnectionStoredContent>(`/tool-connections/${connectionId}/stored-content`),
|
|
deleteStoredContent: (connectionId: string) =>
|
|
api.post<{ deletion: ToolConnectionContentDeletion }>(`/tool-connections/${connectionId}/stored-content/deletion`, {}),
|
|
getStoredContentDeletion: (connectionId: string) =>
|
|
api.get<{ deletion: ToolConnectionContentDeletion | null }>(`/tool-connections/${connectionId}/stored-content/deletion`),
|
|
checkConnectionHealth: (connectionId: string) =>
|
|
api.post<ToolConnectionHealthCheckResult>(`/tool-connections/${connectionId}/health-check`, {}),
|
|
reconnectConnection: (connectionId: string, credentialValues: Record<string, string>) =>
|
|
api.post<ToolConnectionHealthCheckResult>(`/tool-connections/${connectionId}/reconnect`, {
|
|
credentialValues,
|
|
}),
|
|
refreshCatalog: (connectionId: string) =>
|
|
api.post<ToolCatalogRefreshResult>(`/tool-connections/${connectionId}/catalog/refresh`, {}),
|
|
listProviderToolIcons: (companyId: string) =>
|
|
api.get<ProviderToolIconsResponse>(`/companies/${companyId}/tool-icons`),
|
|
listCatalog: (connectionId: string) =>
|
|
api.get<ToolCatalogResponse>(`/tool-connections/${connectionId}/catalog`),
|
|
listConnectionActivity: (connectionId: string, limit = 20) =>
|
|
api.get<ToolConnectionActivityResponse>(
|
|
`/tool-connections/${connectionId}/activity?limit=${limit}`,
|
|
),
|
|
listTestAgents: (connectionId: string) =>
|
|
api.get<ToolConnectionTestAgentsResponse>(
|
|
`/tool-connections/${connectionId}/test-agents`,
|
|
),
|
|
getTestAgentAccess: (connectionId: string, agentId: string) =>
|
|
api.get<ToolConnectionTestAgentAccessResponse>(
|
|
`/tool-connections/${connectionId}/test-agents/${agentId}/access`,
|
|
),
|
|
setupComposioApp: (connectionId: string, toolkit: string, input: ComposioAppSetupInput) =>
|
|
api.post<ComposioAppSetupResult>(`/tool-connections/${connectionId}/composio/apps/${encodeURIComponent(toolkit)}/setup`, input),
|
|
listAggregatorApps: (connectionId: string) => {
|
|
const path = `/tool-connections/${connectionId}/aggregator/apps`;
|
|
// React Query already deduplicates within a viewing-user key. Path-only
|
|
// request coalescing could hand a previous user's in-flight response to a new account.
|
|
detachInflightGet(path);
|
|
return api.get<AggregatorAppsResponse>(path, { cache: "no-store" });
|
|
},
|
|
syncAggregatorApps: (connectionId: string, force = false) => api.post<AggregatorAppsResponse>(`/tool-connections/${connectionId}/aggregator/apps/sync`, { force }),
|
|
refreshAggregatorApps: (connectionId: string, toolkits: string[] = []) => api.post<AggregatorAppsResponse>(`/tool-connections/${connectionId}/aggregator/apps/refresh`, { toolkits }),
|
|
configureArcadeDiscovery: (connectionId: string, input: ArcadeDiscoverySetupInput) => api.put<AggregatorAppsResponse>(`/tool-connections/${connectionId}/aggregator/discovery`, input),
|
|
listComposioApps: (connectionId: string) => api.get<ComposioAppsResponse>(`/tool-connections/${connectionId}/composio/apps`),
|
|
syncComposioApps: (connectionId: string, force = false) => api.post<ComposioAppsResponse>(`/tool-connections/${connectionId}/composio/apps/sync`, { force }),
|
|
refreshComposioApps: (connectionId: string, toolkits: string[]) => api.post<ComposioAppsResponse>(`/tool-connections/${connectionId}/composio/apps/refresh`, { toolkits }),
|
|
manageComposioAppAccount: (connectionId: string, toolkit: string, input: ComposioAppAccountInput) =>
|
|
api.post<ComposioAppSetupResult & { apps: ComposioAppSnapshot[] }>(`/tool-connections/${connectionId}/composio/apps/${encodeURIComponent(toolkit)}/accounts`, input),
|
|
runTestCall: (
|
|
connectionId: string,
|
|
input: { agentId: string; toolName: string; parameters?: Record<string, unknown> },
|
|
) =>
|
|
api.post<ToolConnectionTestCallResult>(
|
|
`/tool-connections/${connectionId}/test-calls`,
|
|
input,
|
|
),
|
|
getTestCallStatus: (connectionId: string, actionRequestId: string) =>
|
|
api.get<ToolConnectionTestCallStatus>(
|
|
`/tool-connections/${connectionId}/test-calls/${actionRequestId}`,
|
|
),
|
|
importMcpJson: (companyId: string, body: { mcpJson: unknown }) =>
|
|
api.post<McpJsonImportPreview>(`/companies/${companyId}/tools/mcp/import-json`, body),
|
|
listStdioTemplates: (companyId: string) =>
|
|
api.get<StdioTemplatesResponse>(`/companies/${companyId}/tools/stdio-templates`),
|
|
createStdioTemplate: (companyId: string, input: CreateStdioTemplateInput) =>
|
|
api.post<StdioTemplateSummary>(`/companies/${companyId}/tools/stdio-templates`, input),
|
|
disableStdioTemplate: (companyId: string, templateId: string, reason?: string | null) =>
|
|
api.post<StdioTemplateSummary>(
|
|
`/companies/${companyId}/tools/stdio-templates/${encodeURIComponent(templateId)}/disable`,
|
|
{ reason: reason ?? null },
|
|
),
|
|
|
|
// --- Profiles ---
|
|
listConnectionProfileConfiguration: (connectionId: string, options?: RequestOptions) =>
|
|
api.get<{ profiles: ToolProfileConfiguration[] }>(`/tool-connections/${connectionId}/profile-configuration`, options),
|
|
listProfiles: (companyId: string) =>
|
|
api.get<ToolProfilesResponse>(`/companies/${companyId}/tools/profiles`),
|
|
getProfileNewTools: (profileId: string) =>
|
|
api.get<ToolProfileNewToolsReview>(`/tool-profiles/${profileId}/new-tools`),
|
|
reviewProfileNewTools: (profileId: string, input: ReviewNewToolsInput) =>
|
|
api.post<ToolProfileNewToolsReviewResult>(`/tool-profiles/${profileId}/new-tools/review`, input),
|
|
createProfile: (companyId: string, input: CreateToolProfileInput) =>
|
|
api.post<ToolProfileWithDetails>(`/companies/${companyId}/tools/profiles`, input),
|
|
updateProfile: (profileId: string, input: UpdateToolProfileInput) =>
|
|
api.patch<ToolProfileWithDetails>(`/tool-profiles/${profileId}`, input),
|
|
duplicateProfile: (
|
|
profileId: string,
|
|
input: { name: string; includeAssignments?: boolean },
|
|
) => api.post<ToolProfileWithDetails>(`/tool-profiles/${profileId}/duplicate`, input),
|
|
deleteProfile: (
|
|
profileId: string,
|
|
input: { force?: boolean; reassignToProfileId?: string } = {},
|
|
) => api.delete<{ deleted: true }>(`/tool-profiles/${profileId}`, input),
|
|
addProfileEntry: (profileId: string, input: ToolProfileEntryInput) =>
|
|
api.post<ToolProfileEntry>(`/tool-profiles/${profileId}/entries`, input),
|
|
updateProfileEntry: (entryId: string, input: Partial<ToolProfileEntryInput>) =>
|
|
api.patch<ToolProfileEntry>(`/tool-profile-entries/${entryId}`, input),
|
|
deleteProfileEntry: (entryId: string) =>
|
|
api.delete<ToolProfileEntry>(`/tool-profile-entries/${entryId}`),
|
|
bindProfile: (companyId: string, profileId: string, input: ToolProfileBindingInput) =>
|
|
api.post<ToolProfileBinding>(`/companies/${companyId}/tools/profiles/${profileId}/bind`, input),
|
|
unbindProfile: (companyId: string, profileId: string, input: UnbindToolProfileInput) =>
|
|
api.post<{ unbound: number }>(`/companies/${companyId}/tools/profiles/${profileId}/unbind`, input),
|
|
getEffectiveProfilesForAgent: (companyId: string, agentId: string) =>
|
|
api.get<ToolProfileEffectiveSummary>(
|
|
`/companies/${companyId}/tools/profiles/effective/agents/${encodeURIComponent(agentId)}`,
|
|
),
|
|
|
|
// --- Runtime ---
|
|
listRuntimeSlots: (companyId: string) =>
|
|
api.get<ToolRuntimeSlotsResponse>(`/companies/${companyId}/tools/runtime-slots`),
|
|
stopRuntimeSlot: (companyId: string, slotId: string) =>
|
|
api.post<ToolRuntimeSlot>(`/companies/${companyId}/tools/runtime-slots/${slotId}/stop`, {}),
|
|
restartRuntimeSlot: (companyId: string, slotId: string) =>
|
|
api.post<ToolRuntimeSlot>(`/companies/${companyId}/tools/runtime-slots/${slotId}/restart`, {}),
|
|
getRuntimeHealth: (companyId: string) =>
|
|
api.get<ToolRuntimeHealthResponse>(`/companies/${companyId}/tools/runtime-health`),
|
|
getRunDecisionLookup: (companyId: string, runId: string) =>
|
|
api.get<ToolRunDecisionLookup>(`/companies/${companyId}/tools/runs/${runId}/decisions`),
|
|
listLiveRuntimeSlots: (companyId: string) =>
|
|
api.get<ToolRuntimeSlot[]>(`/tool-gateway/runtime-slots?companyId=${encodeURIComponent(companyId)}`),
|
|
|
|
// --- Policies (trust rules + decision simulator) ---
|
|
listPolicies: (companyId: string, options?: RequestOptions) =>
|
|
api.get<ToolPoliciesResponse>(`/companies/${companyId}/tools/policies`, options),
|
|
createPolicy: (companyId: string, input: CreateToolPolicy) =>
|
|
api.post<ToolPolicy>(`/companies/${companyId}/tools/policies`, input),
|
|
reorderPolicies: (companyId: string, input: ReorderToolPolicies) =>
|
|
api.post<ToolPoliciesResponse>(`/companies/${companyId}/tools/policies/reorder`, input),
|
|
duplicatePolicy: (companyId: string, policyId: string, input: DuplicateToolPolicy = {}) =>
|
|
api.post<ToolPolicy>(`/companies/${companyId}/tools/policies/${policyId}/duplicate`, input),
|
|
updatePolicy: (companyId: string, policyId: string, input: UpdateToolPolicy) =>
|
|
api.patch<ToolPolicy>(`/companies/${companyId}/tools/policies/${policyId}`, input),
|
|
deletePolicy: (companyId: string, policyId: string) =>
|
|
api.delete<ToolPolicy>(`/companies/${companyId}/tools/policies/${policyId}`),
|
|
listTrustRules: (companyId: string) =>
|
|
api.get<ToolTrustRulesResponse>(`/companies/${companyId}/tools/trust-rules`),
|
|
revokeTrustRule: (companyId: string, policyId: string, reason?: string | null) =>
|
|
api.post<ToolPolicy>(`/companies/${companyId}/tools/trust-rules/${policyId}/revoke`, {
|
|
reason: reason ?? null,
|
|
}),
|
|
testPolicy: (companyId: string, input: Omit<ToolAccessDecisionInput, "companyId">) =>
|
|
api.post<ToolPolicyTestResponse>(`/companies/${companyId}/tools/policy/test`, input),
|
|
|
|
// --- Review queue (Ask first) ---
|
|
listActionRequests: (companyId: string, status: ToolActionRequestStatus = "pending") =>
|
|
api.get<ToolActionRequestsResponse>(
|
|
`/companies/${companyId}/tools/action-requests?status=${encodeURIComponent(status)}`,
|
|
),
|
|
approveActionRequest: (companyId: string, actionRequestId: string, rememberAction = false) =>
|
|
api.post<ToolActionRequest>(`/tool-gateway/action-requests/${actionRequestId}/approve`, { companyId, rememberAction }),
|
|
declineActionRequest: (companyId: string, actionRequestId: string, reason?: string) =>
|
|
api.post<ToolActionRequest>(`/tool-gateway/action-requests/${actionRequestId}/decline`, { companyId, reason }),
|
|
createTrustRuleFromActionRequest: (
|
|
companyId: string,
|
|
actionRequestId: string,
|
|
input: CreateToolTrustRuleFromActionRequest = {},
|
|
) =>
|
|
api.post<ToolPolicy>(
|
|
`/companies/${companyId}/tools/action-requests/${actionRequestId}/trust-rule`,
|
|
input,
|
|
),
|
|
|
|
// --- Named MCP gateways ---
|
|
listGateways: (companyId: string) =>
|
|
api.get<ToolMcpGatewaysResponse>(`/companies/${companyId}/tools/gateways`),
|
|
createGateway: (companyId: string, input: CreateToolMcpGateway) =>
|
|
api.post<ToolMcpGatewayWithTokens>(`/companies/${companyId}/tools/gateways`, input),
|
|
updateGateway: (companyId: string, gatewayId: string, input: UpdateGatewayInput) =>
|
|
api.patch<ToolMcpGatewayWithTokens>(`/tool-gateway/gateways/${gatewayId}`, { ...input, companyId }),
|
|
createGatewayToken: (companyId: string, gatewayId: string, input: CreateGatewayTokenInput) =>
|
|
api.post<ToolMcpGatewayTokenCreated>(`/tool-gateway/gateways/${gatewayId}/tokens`, { ...input, companyId }),
|
|
revealGatewayToken: (companyId: string, tokenId: string) =>
|
|
api.post<ToolMcpGatewayTokenCreated>(`/tool-gateway/gateway-tokens/${tokenId}/reveal`, { companyId }),
|
|
revokeGatewayToken: (companyId: string, tokenId: string) =>
|
|
api.post<ToolMcpGatewayToken>(`/tool-gateway/gateway-tokens/${tokenId}/revoke`, { companyId }),
|
|
|
|
// --- Audit / Activity ---
|
|
/**
|
|
* Humanized Activity feed with server-side filters and cursor pagination.
|
|
* Returns `{ events, nextCursor }`.
|
|
*/
|
|
listActivity: (companyId: string, params: ListActivityParams = {}) => {
|
|
const search = new URLSearchParams({ companyId });
|
|
if (params.gateway) search.set("gateway", params.gateway);
|
|
if (params.app) search.set("app", params.app);
|
|
if (params.agent) search.set("agent", params.agent);
|
|
if (params.outcome) search.set("outcome", params.outcome);
|
|
// Omitting the window is the API's canonical all-time request. This also
|
|
// keeps the page usable during a rolling restart against an older server
|
|
// that does not recognize the newer explicit `all` value.
|
|
if (params.window && params.window !== "all") search.set("window", params.window);
|
|
if (params.search) search.set("search", params.search);
|
|
if (params.cursor) search.set("cursor", params.cursor);
|
|
search.set("limit", String(params.limit ?? 50));
|
|
return api.get<ToolGatewayActivityResponse>(`/tool-gateway/audit?${search.toString()}`);
|
|
},
|
|
/** Flat audit sample (no pagination) — used by derived counters/banners. */
|
|
listAudit: (companyId: string, limit = 100) =>
|
|
api
|
|
.get<ToolGatewayActivityResponse>(
|
|
`/tool-gateway/audit?companyId=${encodeURIComponent(companyId)}&window=30d&limit=${Math.min(limit, 100)}`,
|
|
)
|
|
.then((res) => res.events),
|
|
};
|