Files
PaperClipAI/ui/src/api/tools.ts
T
DottaandClaude Opus 5.5 8af889f612 feat(mcp-apps): view messages with consent, app context, full screen and provider tool icons (#21266)
## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work.
> - MCP Apps (#21119) show interactive widgets from MCP servers, such as
Circleback meeting cards, with the agent's reply in the task chat.
> - The first version deferred three parts of the MCP Apps spec. A
widget could not propose a chat message (`ui/message`). It could not
give the agent context (`ui/update-model-context`). It could not go full
screen.
> - Paperclip also ignored the `icons` that MCP servers declare on tools
(SEP-973).
> - The security review of #21119 showed what these features need from
day one: explicit consent, untrusted-data labels and strict icon
sanitizing.
> - This pull request adds the three host features and provider tool
icons, with those protections built in.
> - The benefit is that widgets can now work with the person and the
agent, not only display data.

## Linked Issues or Issue Description

Refs #21119

**Subsystem affected**
MCP Apps host (task chat widgets), tool catalog, run wake prompt.

**Problem or motivation**
The MCP Apps host refused `ui/message` (-32601), dropped
`ui/update-model-context` and kept every view inline. MCP tool `icons`
were not parsed or shown. So widgets could not ask the agent a
follow-up, the agent could not see what the person selected in a widget,
large widgets were cramped, and tool rows used only generic icons.

**Proposed solution**
Add consent-gated view messages, per-view app context delivered to the
task's next run as untrusted data, a full-screen dialog, and sanitized
provider icons. Details are under "What Changed".

**Alternatives considered**
- Send view messages with a new server route that creates the comment
itself. Rejected: comment creation has many rules (agent chat ownership,
paused conversations, queued delivery, wakeups, receipts). The widget's
Send button uses the same send path as the composer. A small route then
records which view the comment came from.
- Keep the iframe in place for full screen with CSS. Rejected: chat
containers can create containing blocks that break `position: fixed`. A
moved iframe always reloads, so the dialog hosts a new frame instead.

**Roadmap alignment**
Continues the MCP feature work after #21119, #21140 and #21219. It does
not touch the MCP Tasks work (gateway `tools/call` polling and
elicitation).

## What Changed

- **`ui/message`.** The host shows "<App> wants to send: …" with
**Send** and **Dismiss** under the widget (and inside the full-screen
dialog). Nothing is sent before the click. Send posts the text as the
viewer's own comment through the chat's normal send path
(`handleThreadAdd`). `POST
/api/issues/:issueId/mcp-app-views/:viewId/messages` then logs
`issue.mcp_app_message_sent`. It accepts only the caller's own comment
on the same task, matched by `clientRequestId`, from the last 10
minutes. One proposal per view can wait at a time. The view gets `{}`
after the send, or -32000 "Message sending denied" after Dismiss. Only
`user` text up to 8,000 characters is accepted.
- **`ui/update-model-context`.** `PUT
/api/issues/:issueId/mcp-app-views/:viewId/model-context` stores the
latest context per view in `tool_mcp_app_views.model_context` (text
blocks and `structuredContent`, 16 KB at most). Updates are applied in
order and deduped in the browser and on the server. A change logs
`issue.mcp_app_context_updated`, and an empty update clears the context.
The task's next run gets the three most recently updated contexts as an
`## App context (untrusted)` wake-prompt section. The section quotes the
data as JSON and says it is third-party data, not instructions. The read
runs in parallel with the other run preparation and never fails the run.
CLI adapters and the native runner render it through the same
`renderPaperclipWakePrompt`.
- **Who may do this.** Messages and context need a signed-in person with
`issue:comment` on the task. Agents and API keys get 403. Other tasks
and companies get 404. `message` and `updateModelContext` are advertised
in `hostCapabilities` only where the viewer can send messages.
- **Full screen.** The host advertises `availableDisplayModes:
["inline","fullscreen"]` and handles `ui/request-display-mode`. It
honors the view's declared modes and answers with the resulting mode. It
sends `host-context-changed` with `displayMode` and the container (fixed
`height`/`width` in full screen), and again when that container resizes.
A new **Open full screen** control sits next to "Widget from …". Full
screen is a Paperclip dialog that closes with Exit, Escape or the view's
own request.
- **Provider tool icons.** `icons` on MCP tool descriptors are sanitized
into the new `tool_catalog_entries.icons` column, outside the version
hash, so a new icon never quarantines a reviewed tool. Only `https:`
URLs and `data:image/*` URIs are kept, and SVG only as `data:`. A
`data:` icon is at most 32 KB, a URL at most 2,048 characters, with at
most 4 icons per tool. `GET /api/companies/:companyId/tool-icons` lists
them keyed by gateway tool name, in one cached request per chat. Task
chat tool rows and the app's actions list show them through
`ProviderToolIcon`. It renders `<img referrerPolicy="no-referrer">` at a
fixed size and never inlines markup. It checks the source again before
rendering and falls back to the taxonomy icon.
- **Schema.** Migration `0477` adds `tool_catalog_entries.icons`,
`tool_mcp_app_views.model_context` and `model_context_updated_at`, all
nullable.
- **Docs and stories.** `doc/connections/MCP-APPS.md` documents the new
behavior, and the finished items are removed from "Limits and
follow-ups". `Tasks/MCP App views` has new stories: "View asks to send a
message", "Full screen" and "Tool rows with provider icons". The fixture
view now uses `ui/message`, `ui/request-display-mode` and
`ui/update-model-context`.

## Verification

- `pnpm exec vitest run server/src/__tests__/mcp-apps.test.ts
server/src/__tests__/tool-catalog-publication.test.ts
server/src/__tests__/openapi-routes.test.ts
packages/shared/src/mcp-icons.test.ts
packages/shared/src/mcp-apps.test.ts`: pass (embedded Postgres). These
tests cover:
- Context: stored, deduped, logged once, 413 when too large, cleared,
scoped to the task and company, refused for agents (403), and rendered
into the wake prompt as untrusted data.
- Messages: attributed only to the viewer's own recent comment on the
same task. A teammate's comment, an unknown request id or an old comment
gets 404. An agent gets 403.
- Icons: stored sanitized, and the version hash and status do not
change. Another company sees nothing.
- `cd ui && pnpm exec vitest run src/components/mcp-app/
src/components/ProviderToolIcon.test.tsx src/pages/apps/app-detail/`: 69
pass. These tests cover:
- The host protocol for each new method: capabilities, consent wait, one
proposal at a time, invalid input, ordered and deduped context, the size
limit, and the display-mode rules.
  - The consent card (nothing sent without Send).
  - The full-screen dialog (one frame at a time).
  - Icon rendering (no-referrer `img`, no inline SVG, fallback).
- `cd ui && pnpm typecheck` (including Storybook) and `tsc --noEmit` for
the server: clean.
- Red/green: the new route and host tests fail on `master`, where the
routes do not exist and the host answers -32601 or drops updates. The
icon descriptor test failed when the publication write was removed.
- Not run locally: the full suite, and
`packages/adapter-utils/src/server-utils.test.ts › runChildProcess ›
does not crash when the child closes stdin before a delayed write`. That
test times out on this Mac with or without this change, so it is a local
platform issue. CI covers both.

## Risks

- Migration risk is low: three nullable columns, no backfill.
- Every run on a task now does one extra indexed read, in parallel with
the other preparation. Errors are logged and the run continues without
app context.
- If the attribution request fails after the comment is sent, the
comment stays without the `mcp_app_message_sent` activity row. This is
documented.
- Switching between inline and full screen restarts the view, so state
inside the widget resets. This is documented as a limit.
- Icon names shortened with a hash by the gateway (very long names) do
not match, and those rows keep the taxonomy icon.

> For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and
discuss it in `#dev` before opening the PR. Feature PRs that overlap
with planned core work may need to be redirected — check the roadmap
first. See `CONTRIBUTING.md`.

## Model Used

- Claude Opus 5.5 (`claude-opus-5-5`) in Claude Code, with tool use and
code execution. One subagent (the same model) built the provider-icon
part.

## 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
- [ ] 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>
2026-11-13 07:32:48 -06:00

624 lines
28 KiB
TypeScript

import type { AggregatorAppsResponse, ArcadeDiscoverySetupInput } from "@paperclipai/shared/aggregator-apps";
import type { ProviderToolIconsResponse } from "@paperclipai/shared";
import type { ComposioAppAccountInput, ComposioAppSetupInput, ComposioAppSetupResult, ComposioAppSnapshot, ComposioAppsResponse } from "@paperclipai/shared";
import type {
ToolApplication,
ConfigureRailwaySsh,
RailwaySshSetup,
ToolConnection,
ToolConnectionInstall,
ToolConnectionInstallSnapshot,
ToolConnectionRemovalSummary,
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,
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[];
/** 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`),
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),
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) =>
api.get<ToolConnection>(`/tool-connections/${connectionId}`),
// --- 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) =>
api.get<{ connectionId: string; installs: ToolConnectionInstall[] }>(
`/tool-connections/${connectionId}/installs`,
),
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<ConnectionGrant>(`/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) =>
api.delete<ToolConnection & { removal: ToolConnectionRemovalSummary }>(
`/tool-connections/${connectionId}`,
),
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) =>
api.get<{ profiles: ToolProfileConfiguration[] }>(`/tool-connections/${connectionId}/profile-configuration`),
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) =>
api.get<ToolPoliciesResponse>(`/companies/${companyId}/tools/policies`),
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),
};