mirror of
https://github.com/alkimake/paperclip.git
synced 2026-06-15 10:30:37 +09:00
[codex] Add LLM Wiki plugin host support (#5597)
## Thinking Path > - Paperclip orchestrates AI agents for zero-human companies. > - The plugin system needs host contracts and runtime support before large plugins can integrate cleanly. > - The source branch mixed the LLM Wiki package with supporting host/runtime work, managed plugin skills, root-level storage spaces, and a bookmarks reference plugin. > - [PAP-9173](/PAP/issues/PAP-9173) asked for the current branch to be split by file boundary: plugin package separately from everything else. > - [PAP-9188](/PAP/issues/PAP-9188) clarified that LLM Wiki may have plugin-local spaces, but Paperclip core should not reorganize top-level local storage into spaces. > - Follow-up review clarified that the bookmarks example should not ship in this PR either. > - This pull request contains the non-`packages/plugins/plugin-llm-wiki/` host/runtime work, keeps runtime state under the selected Paperclip instance root, and no longer includes the bookmarks example. ## What Changed - Added/updated plugin host contracts, SDK types, worker RPC plumbing, managed plugin skill support, and related server tests. - Removed the bookmarks example plugin package and its bundled-example/workspace references. - Removed the root-level local spaces CLI/migration surface and restored instance-root runtime defaults for config, db, logs, storage, secrets, workspaces, projects, and adapter homes. - Replaced shared root `space-paths` helpers with `home-paths` helpers for core runtime storage. - Tightened stranded recovery unique-conflict detection so concurrent recovery scans reuse the raced recovery issue when Postgres errors are wrapped. - Kept `packages/plugins/plugin-llm-wiki/` out of this PR diff; plugin-local spaces remain in the stacked plugin-only PR. ## Verification - `pnpm exec vitest run cli/src/__tests__/data-dir.test.ts cli/src/__tests__/home-paths.test.ts cli/src/__tests__/onboard.test.ts packages/shared/src/home-paths.test.ts packages/db/src/runtime-config.test.ts server/src/__tests__/agent-instructions-service.test.ts server/src/__tests__/claude-local-execute.test.ts server/src/__tests__/codex-local-execute.test.ts` - `pnpm exec vitest run packages/db/src/runtime-config.test.ts` - `pnpm exec vitest run server/src/__tests__/plugin-routes-authz.test.ts` - `pnpm --filter @paperclipai/server typecheck` - `pnpm exec vitest run server/src/__tests__/heartbeat-process-recovery.test.ts -t "reuses the raced stranded recovery issue"` skipped locally because embedded Postgres did not initialize on this macOS temp host; the code path was typechecked and is covered by Linux CI. - Boundary check: no core references remain for `PAPERCLIP_SPACE_ID`, `spaces migrate-default`, `@paperclipai/shared/space-paths`, `registerSpacesCommands`, or the removed bookmarks example. - Previous PR head `4f23e034` had green GitHub checks: `verify`, all four serialized server shards, `e2e`, `Canary Dry Run`, `policy`, Snyk, and `Greptile Review`. Current head `582f466d` is re-running checks after the bookmarks deletion. ## Risks - Plugin host changes touch shared runtime paths, so regressions would most likely appear in adapter startup, plugin loading, or local dev path defaults. - Removing the bookmarks example also removes one demonstration of plugin database namespaces plus local-folder persistence; remaining plugin examples still cover bundled example discovery and plugin host flows. - The plugin package itself is intentionally deferred to the stacked plugin-only PR, where LLM Wiki plugin-local spaces live. - Existing installs that tested the transient root-level spaces CLI should stop using it; this PR intentionally removes that unsupported migration surface before merge. > 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 - OpenAI GPT-5 Codex via Codex CLI, tool use and local code execution enabled; context window not exposed. ## 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 run tests locally and they pass, except where noted above for host-specific embedded Postgres initialization - [x] I have added or updated tests where applicable - [x] 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 Stacked follow-up: PR #5592 contains only `packages/plugins/plugin-llm-wiki/` and targets this branch. --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
GitHub
parent
eb12c42009
commit
0096b56a1c
40 changed files with 1892 additions and 224 deletions
|
|
@ -7,6 +7,8 @@ import type {
|
|||
PluginIssueOriginKind,
|
||||
PluginManagedAgentResolution,
|
||||
PluginManagedRoutineResolution,
|
||||
PluginManagedSkillResolution,
|
||||
CompanySkill,
|
||||
Company,
|
||||
Project,
|
||||
Routine,
|
||||
|
|
@ -33,6 +35,8 @@ import type {
|
|||
PluginWorkspace,
|
||||
AgentSession,
|
||||
AgentSessionEvent,
|
||||
PluginLocalFolderEntry,
|
||||
PluginLocalFolderStatus,
|
||||
} from "./types.js";
|
||||
import type {
|
||||
PluginEnvironmentValidateConfigParams,
|
||||
|
|
@ -434,6 +438,8 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
|||
const agents = new Map<string, Agent>();
|
||||
const goals = new Map<string, Goal>();
|
||||
const projectWorkspaces = new Map<string, PluginWorkspace[]>();
|
||||
const localFolderStatuses = new Map<string, PluginLocalFolderStatus>();
|
||||
const localFolderFiles = new Map<string, string>();
|
||||
|
||||
const sessions = new Map<string, AgentSession>();
|
||||
const sessionEventCallbacks = new Map<string, (event: AgentSessionEvent) => void>();
|
||||
|
|
@ -445,6 +451,43 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
|||
const actionHandlers = new Map<string, (params: Record<string, unknown>) => Promise<unknown>>();
|
||||
const toolHandlers = new Map<string, (params: unknown, runCtx: ToolRunContext) => Promise<ToolResult>>();
|
||||
|
||||
function localFolderKey(companyId: string, folderKey: string): string {
|
||||
return `${companyId}:${folderKey}`;
|
||||
}
|
||||
|
||||
function localFolderFileKey(companyId: string, folderKey: string, relativePath: string): string {
|
||||
return `${localFolderKey(companyId, folderKey)}:${relativePath}`;
|
||||
}
|
||||
|
||||
function normalizeLocalFolderRelativePath(relativePath: string): string {
|
||||
const parts: string[] = [];
|
||||
for (const segment of relativePath.split(/[\\/]+/)) {
|
||||
if (!segment || segment === ".") continue;
|
||||
if (segment === "..") throw new Error("Local folder path traversal is not allowed");
|
||||
parts.push(segment);
|
||||
}
|
||||
return parts.join("/");
|
||||
}
|
||||
|
||||
function notConfiguredLocalFolderStatus(folderKey: string): PluginLocalFolderStatus {
|
||||
return {
|
||||
folderKey,
|
||||
configured: false,
|
||||
path: null,
|
||||
realPath: null,
|
||||
access: "readWrite",
|
||||
readable: false,
|
||||
writable: false,
|
||||
requiredDirectories: [],
|
||||
requiredFiles: [],
|
||||
missingDirectories: [],
|
||||
missingFiles: [],
|
||||
healthy: false,
|
||||
problems: [{ code: "not_configured", message: "No local folder path is configured." }],
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
}
|
||||
|
||||
function issueRelationSummary(issueId: string) {
|
||||
const issue = issues.get(issueId);
|
||||
if (!issue) throw new Error(`Issue not found: ${issueId}`);
|
||||
|
|
@ -541,7 +584,7 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
|||
},
|
||||
async configure(input) {
|
||||
requireCapability(manifest, capabilitySet, "local.folders");
|
||||
return {
|
||||
const status = {
|
||||
folderKey: input.folderKey,
|
||||
configured: true,
|
||||
path: input.path,
|
||||
|
|
@ -556,58 +599,98 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
|||
healthy: true,
|
||||
problems: [],
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
} satisfies PluginLocalFolderStatus;
|
||||
localFolderStatuses.set(localFolderKey(input.companyId, input.folderKey), status);
|
||||
return status;
|
||||
},
|
||||
async status(_companyId, folderKey) {
|
||||
async status(companyId, folderKey) {
|
||||
requireCapability(manifest, capabilitySet, "local.folders");
|
||||
return {
|
||||
folderKey,
|
||||
configured: false,
|
||||
path: null,
|
||||
realPath: null,
|
||||
access: "readWrite",
|
||||
readable: false,
|
||||
writable: false,
|
||||
requiredDirectories: [],
|
||||
requiredFiles: [],
|
||||
missingDirectories: [],
|
||||
missingFiles: [],
|
||||
healthy: false,
|
||||
problems: [{ code: "not_configured", message: "No local folder path is configured." }],
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
return localFolderStatuses.get(localFolderKey(companyId, folderKey)) ?? notConfiguredLocalFolderStatus(folderKey);
|
||||
},
|
||||
async list(_companyId, folderKey, options) {
|
||||
async list(companyId, folderKey, options) {
|
||||
requireCapability(manifest, capabilitySet, "local.folders");
|
||||
const status = localFolderStatuses.get(localFolderKey(companyId, folderKey));
|
||||
if (!status?.configured) throw new Error("Local folder is not configured");
|
||||
const prefix = normalizeLocalFolderRelativePath(options?.relativePath ?? "");
|
||||
const prefixWithSlash = prefix ? `${prefix}/` : "";
|
||||
const entries = new Map<string, PluginLocalFolderEntry>();
|
||||
for (const [key, contents] of localFolderFiles) {
|
||||
const filePrefix = `${localFolderKey(companyId, folderKey)}:`;
|
||||
if (!key.startsWith(filePrefix)) continue;
|
||||
const filePath = key.slice(filePrefix.length);
|
||||
if (prefix && filePath !== prefix && !filePath.startsWith(prefixWithSlash)) continue;
|
||||
const remainder = prefix ? filePath.slice(prefixWithSlash.length) : filePath;
|
||||
const [name] = remainder.split("/");
|
||||
if (!name) continue;
|
||||
const entryPath = prefix ? `${prefix}/${name}` : name;
|
||||
const isNested = remainder.includes("/");
|
||||
if (!options?.recursive && isNested) {
|
||||
entries.set(entryPath, {
|
||||
path: entryPath,
|
||||
name,
|
||||
kind: "directory",
|
||||
size: null,
|
||||
modifiedAt: null,
|
||||
});
|
||||
continue;
|
||||
}
|
||||
entries.set(filePath, {
|
||||
path: filePath,
|
||||
name: filePath.split("/").pop() ?? filePath,
|
||||
kind: "file",
|
||||
size: Buffer.byteLength(contents, "utf8"),
|
||||
modifiedAt: null,
|
||||
});
|
||||
}
|
||||
const maxEntries = options?.maxEntries && options.maxEntries > 0 ? options.maxEntries : entries.size;
|
||||
const allEntries = [...entries.values()].sort((a, b) => a.path.localeCompare(b.path));
|
||||
return {
|
||||
folderKey,
|
||||
relativePath: options?.relativePath ?? null,
|
||||
entries: [],
|
||||
truncated: false,
|
||||
entries: allEntries.slice(0, maxEntries),
|
||||
truncated: allEntries.length > maxEntries,
|
||||
};
|
||||
},
|
||||
async readText() {
|
||||
async readText(companyId, folderKey, relativePath) {
|
||||
requireCapability(manifest, capabilitySet, "local.folders");
|
||||
throw new Error("Test harness local folder readText is not implemented");
|
||||
const normalizedPath = normalizeLocalFolderRelativePath(relativePath);
|
||||
const contents = localFolderFiles.get(localFolderFileKey(companyId, folderKey, normalizedPath));
|
||||
if (contents === undefined) throw new Error(`Local folder file not found: ${relativePath}`);
|
||||
return contents;
|
||||
},
|
||||
async writeTextAtomic(_companyId, folderKey) {
|
||||
async writeTextAtomic(companyId, folderKey, relativePath, contents) {
|
||||
requireCapability(manifest, capabilitySet, "local.folders");
|
||||
return {
|
||||
const status = localFolderStatuses.get(localFolderKey(companyId, folderKey)) ?? {
|
||||
folderKey,
|
||||
configured: false,
|
||||
path: null,
|
||||
realPath: null,
|
||||
configured: true,
|
||||
path: `memory://${manifest.id}/${companyId}/${folderKey}`,
|
||||
realPath: `memory://${manifest.id}/${companyId}/${folderKey}`,
|
||||
access: "readWrite",
|
||||
readable: false,
|
||||
writable: false,
|
||||
readable: true,
|
||||
writable: true,
|
||||
requiredDirectories: [],
|
||||
requiredFiles: [],
|
||||
missingDirectories: [],
|
||||
missingFiles: [],
|
||||
healthy: false,
|
||||
problems: [{ code: "not_configured", message: "No local folder path is configured." }],
|
||||
healthy: true,
|
||||
problems: [],
|
||||
checkedAt: new Date().toISOString(),
|
||||
};
|
||||
} satisfies PluginLocalFolderStatus;
|
||||
if (status.access !== "readWrite" || !status.writable) {
|
||||
throw new Error("Local folder is not configured for writes");
|
||||
}
|
||||
localFolderStatuses.set(localFolderKey(companyId, folderKey), status);
|
||||
localFolderFiles.set(localFolderFileKey(companyId, folderKey, normalizeLocalFolderRelativePath(relativePath)), contents);
|
||||
return status;
|
||||
},
|
||||
async deleteFile(companyId, folderKey, relativePath) {
|
||||
requireCapability(manifest, capabilitySet, "local.folders");
|
||||
const status = localFolderStatuses.get(localFolderKey(companyId, folderKey)) ?? notConfiguredLocalFolderStatus(folderKey);
|
||||
if (status.configured && (status.access !== "readWrite" || !status.writable)) {
|
||||
throw new Error("Local folder is not configured for writes");
|
||||
}
|
||||
localFolderFiles.delete(localFolderFileKey(companyId, folderKey, normalizeLocalFolderRelativePath(relativePath)));
|
||||
return status;
|
||||
},
|
||||
},
|
||||
events: {
|
||||
|
|
@ -991,14 +1074,14 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
|||
concurrencyPolicy: declaration.concurrencyPolicy ?? "coalesce_if_active",
|
||||
catchUpPolicy: declaration.catchUpPolicy ?? "skip_missed",
|
||||
variables: declaration.variables ?? [],
|
||||
latestRevisionId: null,
|
||||
latestRevisionNumber: 1,
|
||||
createdByAgentId: null,
|
||||
createdByUserId: null,
|
||||
updatedByAgentId: null,
|
||||
updatedByUserId: null,
|
||||
lastTriggeredAt: null,
|
||||
lastEnqueuedAt: null,
|
||||
latestRevisionId: null,
|
||||
latestRevisionNumber: 1,
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
managedByPlugin: {
|
||||
|
|
@ -1087,6 +1170,174 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
|||
},
|
||||
},
|
||||
},
|
||||
skills: {
|
||||
managed: {
|
||||
async get(skillKey, companyId) {
|
||||
requireCapability(manifest, capabilitySet, "skills.managed");
|
||||
const declaration = manifest.skills?.find((skill) => skill.skillKey === skillKey);
|
||||
if (!declaration) {
|
||||
return {
|
||||
pluginKey: manifest.id,
|
||||
resourceKind: "skill",
|
||||
resourceKey: skillKey,
|
||||
companyId,
|
||||
skillId: null,
|
||||
skill: null,
|
||||
status: "missing",
|
||||
defaultDrift: null,
|
||||
} satisfies PluginManagedSkillResolution;
|
||||
}
|
||||
const externalId = `${manifest.id}:skill:${skillKey}`;
|
||||
const existingEntity = [...entities.values()].find((entity) =>
|
||||
entity.entityType === "managed_resource"
|
||||
&& entity.scopeKind === "company"
|
||||
&& entity.scopeId === companyId
|
||||
&& entity.externalId === externalId
|
||||
);
|
||||
const existingSkill = existingEntity?.data?.skill as CompanySkill | undefined;
|
||||
if (existingSkill && existingSkill.companyId === companyId) {
|
||||
return {
|
||||
pluginKey: manifest.id,
|
||||
resourceKind: "skill",
|
||||
resourceKey: skillKey,
|
||||
companyId,
|
||||
skillId: existingSkill.id,
|
||||
skill: existingSkill,
|
||||
status: "resolved",
|
||||
defaultDrift: null,
|
||||
} satisfies PluginManagedSkillResolution;
|
||||
}
|
||||
return {
|
||||
pluginKey: manifest.id,
|
||||
resourceKind: "skill",
|
||||
resourceKey: skillKey,
|
||||
companyId,
|
||||
skillId: null,
|
||||
skill: null,
|
||||
status: "missing",
|
||||
defaultDrift: null,
|
||||
} satisfies PluginManagedSkillResolution;
|
||||
},
|
||||
async reconcile(skillKey, companyId) {
|
||||
const existing = await this.get(skillKey, companyId);
|
||||
if (existing.skill) return existing;
|
||||
const declaration = manifest.skills?.find((skill) => skill.skillKey === skillKey);
|
||||
if (!declaration) return existing;
|
||||
const now = new Date();
|
||||
const skill = {
|
||||
id: randomUUID(),
|
||||
companyId,
|
||||
key: `plugin/${manifest.id.replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}/${skillKey}`,
|
||||
slug: declaration.slug ?? skillKey,
|
||||
name: declaration.displayName,
|
||||
description: declaration.description ?? null,
|
||||
markdown: declaration.markdown ?? `# ${declaration.displayName}\n`,
|
||||
sourceType: "catalog",
|
||||
sourceLocator: null,
|
||||
sourceRef: null,
|
||||
trustLevel: "markdown_only",
|
||||
compatibility: "compatible",
|
||||
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
|
||||
metadata: {
|
||||
sourceKind: "catalog",
|
||||
pluginManagedResource: {
|
||||
pluginKey: manifest.id,
|
||||
resourceKind: "skill",
|
||||
resourceKey: skillKey,
|
||||
},
|
||||
},
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
} satisfies CompanySkill;
|
||||
const nowIso = now.toISOString();
|
||||
const record: PluginEntityRecord = {
|
||||
id: randomUUID(),
|
||||
entityType: "managed_resource",
|
||||
scopeKind: "company",
|
||||
scopeId: companyId,
|
||||
externalId: `${manifest.id}:skill:${skillKey}`,
|
||||
title: declaration.displayName,
|
||||
status: null,
|
||||
data: { resourceKind: "skill", resourceKey: skillKey, skillId: skill.id, skill },
|
||||
createdAt: nowIso,
|
||||
updatedAt: nowIso,
|
||||
};
|
||||
entities.set(record.id, record);
|
||||
return {
|
||||
pluginKey: manifest.id,
|
||||
resourceKind: "skill",
|
||||
resourceKey: skillKey,
|
||||
companyId,
|
||||
skillId: skill.id,
|
||||
skill,
|
||||
status: "created",
|
||||
defaultDrift: null,
|
||||
} satisfies PluginManagedSkillResolution;
|
||||
},
|
||||
async reset(skillKey, companyId) {
|
||||
requireCapability(manifest, capabilitySet, "skills.managed");
|
||||
const existing = await this.get(skillKey, companyId);
|
||||
const declaration = manifest.skills?.find((skill) => skill.skillKey === skillKey);
|
||||
if (!declaration) return existing;
|
||||
const now = new Date();
|
||||
const skill = {
|
||||
id: existing.skill?.id ?? randomUUID(),
|
||||
companyId,
|
||||
key: `plugin/${manifest.id.replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "")}/${skillKey}`,
|
||||
slug: declaration.slug ?? skillKey,
|
||||
name: declaration.displayName,
|
||||
description: declaration.description ?? null,
|
||||
markdown: declaration.markdown ?? `# ${declaration.displayName}\n`,
|
||||
sourceType: "catalog",
|
||||
sourceLocator: null,
|
||||
sourceRef: null,
|
||||
trustLevel: "markdown_only",
|
||||
compatibility: "compatible",
|
||||
fileInventory: [{ path: "SKILL.md", kind: "skill" }],
|
||||
metadata: {
|
||||
sourceKind: "catalog",
|
||||
pluginManagedResource: {
|
||||
pluginKey: manifest.id,
|
||||
resourceKind: "skill",
|
||||
resourceKey: skillKey,
|
||||
},
|
||||
},
|
||||
createdAt: existing.skill?.createdAt ?? now,
|
||||
updatedAt: now,
|
||||
} satisfies CompanySkill;
|
||||
const nowIso = now.toISOString();
|
||||
const existingEntity = [...entities.values()].find((entity) =>
|
||||
entity.entityType === "managed_resource" &&
|
||||
entity.scopeKind === "company" &&
|
||||
entity.scopeId === companyId &&
|
||||
entity.externalId === `${manifest.id}:skill:${skillKey}`,
|
||||
);
|
||||
const record: PluginEntityRecord = {
|
||||
id: existingEntity?.id ?? randomUUID(),
|
||||
entityType: "managed_resource",
|
||||
scopeKind: "company",
|
||||
scopeId: companyId,
|
||||
externalId: `${manifest.id}:skill:${skillKey}`,
|
||||
title: declaration.displayName,
|
||||
status: null,
|
||||
data: { resourceKind: "skill", resourceKey: skillKey, skillId: skill.id, skill },
|
||||
createdAt: existingEntity?.createdAt ?? nowIso,
|
||||
updatedAt: nowIso,
|
||||
};
|
||||
entities.set(record.id, record);
|
||||
return {
|
||||
pluginKey: manifest.id,
|
||||
resourceKind: "skill",
|
||||
resourceKey: skillKey,
|
||||
companyId,
|
||||
skillId: skill.id,
|
||||
skill,
|
||||
status: "reset",
|
||||
defaultDrift: null,
|
||||
} satisfies PluginManagedSkillResolution;
|
||||
},
|
||||
},
|
||||
},
|
||||
companies: {
|
||||
async list(input) {
|
||||
requireCapability(manifest, capabilitySet, "companies.read");
|
||||
|
|
@ -1147,7 +1398,7 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
|||
title: input.title,
|
||||
description: input.description ?? null,
|
||||
status: input.status ?? "todo",
|
||||
workMode: input.workMode ?? "standard",
|
||||
workMode: "standard",
|
||||
priority: input.priority ?? "medium",
|
||||
assigneeAgentId: input.assigneeAgentId ?? null,
|
||||
assigneeUserId: input.assigneeUserId ?? null,
|
||||
|
|
@ -1164,7 +1415,7 @@ export function createTestHarness(options: TestHarnessOptions): TestHarness {
|
|||
originRunId: input.originRunId ?? null,
|
||||
requestDepth: input.requestDepth ?? 0,
|
||||
billingCode: input.billingCode ?? null,
|
||||
assigneeAdapterOverrides: null,
|
||||
assigneeAdapterOverrides: input.assigneeAdapterOverrides ?? null,
|
||||
executionWorkspaceId: input.executionWorkspaceId ?? null,
|
||||
executionWorkspacePreference: input.executionWorkspacePreference ?? null,
|
||||
executionWorkspaceSettings: input.executionWorkspaceSettings ?? null,
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue