mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-15 10:30:37 +09:00
feat(adapters): add capability flags to ServerAdapterModule (#3540)
## Thinking Path > - Paperclip orchestrates AI agents via adapters (`claude_local`, `codex_local`, etc.) > - Each adapter type has different capabilities — instructions bundles, skill materialization, local JWT — but these were gated by 5 hardcoded type lists scattered across server routes and UI components > - External adapter plugins (e.g. a future `opencode_k8s`) cannot add themselves to those hardcoded lists without patching Paperclip source > - The existing `supportsLocalAgentJwt` field on `ServerAdapterModule` proves the right pattern already exists; it just wasn't applied to the other capability gates > - This pull request replaces the 4 remaining hardcoded lists with declarative capability flags on `ServerAdapterModule`, exposed through the adapter listing API > - The benefit is that external adapter plugins can now declare their own capabilities without any changes to Paperclip source code ## What Changed - **`packages/adapter-utils/src/types.ts`** — added optional capability fields to `ServerAdapterModule`: `supportsInstructionsBundle`, `instructionsPathKey`, `requiresMaterializedRuntimeSkills` - **`server/src/routes/agents.ts`** — replaced `DEFAULT_MANAGED_INSTRUCTIONS_ADAPTER_TYPES` and `ADAPTERS_REQUIRING_MATERIALIZED_RUNTIME_SKILLS` hardcoded sets with capability-aware helper functions that fall back to the legacy sets for adapters that don't set flags - **`server/src/routes/adapters.ts`** — `GET /api/adapters` now includes a `capabilities` object per adapter (all four flags + derived `supportsSkills`) - **`server/src/adapters/registry.ts`** — all built-in adapters (`claude_local`, `codex_local`, `process`, `cursor`) now declare flags explicitly - **`ui/src/adapters/use-adapter-capabilities.ts`** — new hook that fetches adapter capabilities from the API - **`ui/src/pages/AgentDetail.tsx`** — replaced hardcoded `isLocal` allowlist with `capabilities.supportsInstructionsBundle` from the API - **`ui/src/components/AgentConfigForm.tsx`** / **`OnboardingWizard.tsx`** — replaced `NONLOCAL_TYPES` denylist with capability-based checks - **`server/src/__tests__/adapter-registry.test.ts`** / **`adapter-routes.test.ts`** — tests covering flag exposure, undefined-when-unset, and per-adapter values - **`docs/adapters/creating-an-adapter.md`** — new "Capability Flags" section documenting all flags and an example for external plugin authors ## Verification - Run `pnpm test --filter=@paperclip/server -- adapter-registry adapter-routes` — all new tests pass - Run `pnpm test --filter=@paperclip/adapter-utils` — existing tests still pass - Spin up dev server, open an agent with `claude_local` type — instructions bundle tab still visible - Create/open an agent with a non-local type — instructions bundle tab still hidden - Call `GET /api/adapters` and verify each adapter includes a `capabilities` object with the correct flags ## Risks - **Low risk overall** — all new flags are optional with backwards-compatible fallbacks to the existing hardcoded sets; no adapter behaviour changes unless a flag is explicitly set - Adapters that do not declare flags continue to use the legacy lists, so there is no regression risk for built-in adapters - The UI capability hook adds one API call to AgentDetail mount; this is a pre-existing endpoint, so no new latency path is introduced ## Model Used - Provider: Anthropic - Model: Claude Sonnet 4.6 (`claude-sonnet-4-6`) - Context: 200k token context window - Mode: Agentic tool use (code editing, bash, grep, file reads) ## 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 run tests locally and they pass - [x] I have added or updated tests where applicable - [ ] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge --------- Co-authored-by: Pawla Abdul (Bot) <pawla@groombook.dev> Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Chris Farhood
GitHub
parent
f6ce976544
commit
50cd76d8a3
13 changed files with 329 additions and 15 deletions
|
|
@ -59,6 +59,13 @@ interface AdapterInstallRequest {
|
|||
version?: string;
|
||||
}
|
||||
|
||||
interface AdapterCapabilities {
|
||||
supportsInstructionsBundle: boolean;
|
||||
supportsSkills: boolean;
|
||||
supportsLocalAgentJwt: boolean;
|
||||
requiresMaterializedRuntimeSkills: boolean;
|
||||
}
|
||||
|
||||
interface AdapterInfo {
|
||||
type: string;
|
||||
label: string;
|
||||
|
|
@ -66,6 +73,7 @@ interface AdapterInfo {
|
|||
modelsCount: number;
|
||||
loaded: boolean;
|
||||
disabled: boolean;
|
||||
capabilities: AdapterCapabilities;
|
||||
/** True when an external plugin has replaced a built-in adapter of the same type. */
|
||||
overriddenBuiltin?: boolean;
|
||||
/** True when the external override for a builtin type is currently paused. */
|
||||
|
|
@ -103,6 +111,15 @@ function readAdapterPackageVersionFromDisk(record: AdapterPluginRecord): string
|
|||
}
|
||||
}
|
||||
|
||||
function buildAdapterCapabilities(adapter: ServerAdapterModule): AdapterCapabilities {
|
||||
return {
|
||||
supportsInstructionsBundle: adapter.supportsInstructionsBundle ?? false,
|
||||
supportsSkills: Boolean(adapter.listSkills || adapter.syncSkills),
|
||||
supportsLocalAgentJwt: adapter.supportsLocalAgentJwt ?? false,
|
||||
requiresMaterializedRuntimeSkills: adapter.requiresMaterializedRuntimeSkills ?? false,
|
||||
};
|
||||
}
|
||||
|
||||
function buildAdapterInfo(adapter: ServerAdapterModule, externalRecord: AdapterPluginRecord | undefined, disabledSet: Set<string>): AdapterInfo {
|
||||
const fromDisk = externalRecord ? readAdapterPackageVersionFromDisk(externalRecord) : undefined;
|
||||
return {
|
||||
|
|
@ -112,6 +129,7 @@ function buildAdapterInfo(adapter: ServerAdapterModule, externalRecord: AdapterP
|
|||
modelsCount: (adapter.models ?? []).length,
|
||||
loaded: true, // If it's in the registry, it's loaded
|
||||
disabled: disabledSet.has(adapter.type),
|
||||
capabilities: buildAdapterCapabilities(adapter),
|
||||
overriddenBuiltin: externalRecord ? BUILTIN_ADAPTER_TYPES.has(adapter.type) : undefined,
|
||||
overridePaused: BUILTIN_ADAPTER_TYPES.has(adapter.type) ? isOverridePaused(adapter.type) : undefined,
|
||||
// Prefer on-disk package.json so the UI reflects bumps without relying on store-only fields.
|
||||
|
|
|
|||
|
|
@ -72,6 +72,8 @@ import {
|
|||
import { getTelemetryClient } from "../telemetry.js";
|
||||
|
||||
export function agentRoutes(db: Db) {
|
||||
// Legacy hardcoded maps — used as fallback when adapter module does not
|
||||
// declare capability flags explicitly.
|
||||
const DEFAULT_INSTRUCTIONS_PATH_KEYS: Record<string, string> = {
|
||||
claude_local: "instructionsFilePath",
|
||||
codex_local: "instructionsFilePath",
|
||||
|
|
@ -83,6 +85,22 @@ export function agentRoutes(db: Db) {
|
|||
pi_local: "instructionsFilePath",
|
||||
};
|
||||
const DEFAULT_MANAGED_INSTRUCTIONS_ADAPTER_TYPES = new Set(Object.keys(DEFAULT_INSTRUCTIONS_PATH_KEYS));
|
||||
|
||||
/** Check if an adapter supports the managed instructions bundle. */
|
||||
function adapterSupportsInstructionsBundle(adapterType: string): boolean {
|
||||
const adapter = findActiveServerAdapter(adapterType);
|
||||
if (adapter?.supportsInstructionsBundle !== undefined) return adapter.supportsInstructionsBundle;
|
||||
return DEFAULT_MANAGED_INSTRUCTIONS_ADAPTER_TYPES.has(adapterType);
|
||||
}
|
||||
|
||||
/** Resolve the adapter config key for the instructions file path. */
|
||||
function resolveInstructionsPathKey(adapterType: string): string | null {
|
||||
const adapter = findActiveServerAdapter(adapterType);
|
||||
if (adapter?.instructionsPathKey) return adapter.instructionsPathKey;
|
||||
if (adapter?.supportsInstructionsBundle === true) return "instructionsFilePath";
|
||||
if (adapter?.supportsInstructionsBundle === false) return null;
|
||||
return DEFAULT_INSTRUCTIONS_PATH_KEYS[adapterType] ?? null;
|
||||
}
|
||||
const KNOWN_INSTRUCTIONS_PATH_KEYS = new Set(["instructionsFilePath", "agentsMdPath"]);
|
||||
const KNOWN_INSTRUCTIONS_BUNDLE_KEYS = [
|
||||
"instructionsBundleMode",
|
||||
|
|
@ -557,7 +575,7 @@ export function agentRoutes(db: Db) {
|
|||
adapterType: string;
|
||||
adapterConfig: unknown;
|
||||
}>(agent: T): Promise<T> {
|
||||
if (!DEFAULT_MANAGED_INSTRUCTIONS_ADAPTER_TYPES.has(agent.adapterType)) {
|
||||
if (!adapterSupportsInstructionsBundle(agent.adapterType)) {
|
||||
return agent;
|
||||
}
|
||||
|
||||
|
|
@ -638,7 +656,9 @@ export function agentRoutes(db: Db) {
|
|||
};
|
||||
}
|
||||
|
||||
const ADAPTERS_REQUIRING_MATERIALIZED_RUNTIME_SKILLS = new Set([
|
||||
// Legacy hardcoded set — used as fallback when adapter module does not
|
||||
// declare requiresMaterializedRuntimeSkills explicitly.
|
||||
const LEGACY_MATERIALIZED_SKILLS_SET = new Set([
|
||||
"cursor",
|
||||
"gemini_local",
|
||||
"opencode_local",
|
||||
|
|
@ -646,7 +666,11 @@ export function agentRoutes(db: Db) {
|
|||
]);
|
||||
|
||||
function shouldMaterializeRuntimeSkillsForAdapter(adapterType: string) {
|
||||
return ADAPTERS_REQUIRING_MATERIALIZED_RUNTIME_SKILLS.has(adapterType);
|
||||
const adapter = findActiveServerAdapter(adapterType);
|
||||
if (adapter?.requiresMaterializedRuntimeSkills !== undefined) {
|
||||
return adapter.requiresMaterializedRuntimeSkills;
|
||||
}
|
||||
return LEGACY_MATERIALIZED_SKILLS_SET.has(adapterType);
|
||||
}
|
||||
|
||||
async function buildRuntimeSkillConfig(
|
||||
|
|
@ -1617,7 +1641,7 @@ export function agentRoutes(db: Db) {
|
|||
|
||||
const existingAdapterConfig = asRecord(existing.adapterConfig) ?? {};
|
||||
const explicitKey = asNonEmptyString(req.body.adapterConfigKey);
|
||||
const defaultKey = DEFAULT_INSTRUCTIONS_PATH_KEYS[existing.adapterType] ?? null;
|
||||
const defaultKey = resolveInstructionsPathKey(existing.adapterType);
|
||||
const adapterConfigKey = explicitKey ?? defaultKey;
|
||||
if (!adapterConfigKey) {
|
||||
res.status(422).json({
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue