gb_flea/paperclip
1
0
Fork 0
forked from farhoodlabs/paperclip
Code Pull Requests Activity

[codex] Add LLM Wiki plugin host support (#5597)

Browse Source 
## 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
2026-05-10 07:34:12 -05:00
committed by GitHub
parent eb12c42009
commit 0096b56a1c
40 changed files with 1892 additions and 224 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/adapter-utils/src/server-utils.ts
+22
View File
@@ -1,6 +1,7 @@
import { spawn, type ChildProcess } from "node:child_process";
import { createHash, randomUUID } from "node:crypto";
import { constants as fsConstants, promises as fs, type Dirent } from "node:fs";
import os from "node:os";
import path from "node:path";
import { sanitizeRemoteExecutionEnv } from "./remote-execution-env.js";
import { buildSshSpawnTarget, type SshRemoteExecutionSpec } from "./ssh.js";
@@ -78,6 +79,8 @@ export const runningProcesses = new Map<string, RunningProcess>();
export const MAX_CAPTURE_BYTES = 4 * 1024 * 1024;
export const MAX_EXCERPT_BYTES = 32 * 1024;
const TERMINAL_RESULT_SCAN_OVERLAP_CHARS = 64 * 1024;
const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
const SENSITIVE_ENV_KEY = /(key|token|secret|password|passwd|authorization|cookie)/i;
const REDACTED_LOG_VALUE = "***REDACTED***";
const PAPERCLIP_SKILL_ROOT_RELATIVE_CANDIDATES = [
@@ -88,6 +91,25 @@ const MATERIALIZED_SKILL_SENTINEL = ".paperclip-materialized-skill.json";
const MATERIALIZED_SKILL_LOCK_OWNER = "owner.json";
const MATERIALIZED_SKILL_LOCK_STALE_MS = 30_000;
function expandHomePrefix(value: string): string {
if (value === "~") return os.homedir();
if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
return value;
}
export function resolvePaperclipInstanceRootForAdapter(input: {
homeDir?: string;
instanceId?: string;
env?: NodeJS.ProcessEnv;
} = {}): string {
const env = input.env ?? process.env;
const homeRaw = input.homeDir?.trim() || env.PAPERCLIP_HOME?.trim();
const homeDir = path.resolve(homeRaw ? expandHomePrefix(homeRaw) : path.resolve(os.homedir(), ".paperclip"));
const instanceId = input.instanceId?.trim() || env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_PAPERCLIP_INSTANCE_ID;
if (!PATH_SEGMENT_RE.test(instanceId)) throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${instanceId}'.`);
return path.resolve(homeDir, "instances", instanceId);
}
export const DEFAULT_PAPERCLIP_AGENT_PROMPT_TEMPLATE = [
"You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
"",
packages/adapters/acpx-local/src/server/execute.ts
+5 -1
View File
@@ -21,6 +21,7 @@ import {
readPaperclipIssueWorkModeFromContext,
renderPaperclipWakePrompt,
renderTemplate,
resolvePaperclipInstanceRootForAdapter,
resolvePaperclipDesiredSkillNames,
rewriteWorkspaceCwdEnvVarsForExecution,
shapePaperclipWorkspaceEnvForExecution,
@@ -115,7 +116,10 @@ function shortHash(value: unknown): string {
function defaultPaperclipInstanceDir(): string {
const home = process.env.PAPERCLIP_HOME?.trim() || path.join(os.homedir(), ".paperclip");
const instanceId = process.env.PAPERCLIP_INSTANCE_ID?.trim() || "default";
return path.join(home, "instances", instanceId);
return resolvePaperclipInstanceRootForAdapter({
homeDir: home,
instanceId,
});
}
function defaultStateDir(companyId: string, agentId: string): string {
packages/adapters/claude-local/src/server/claude-config.ts
+8 -5
View File
@@ -3,8 +3,8 @@ import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
import { resolvePaperclipInstanceRootForAdapter } from "@paperclipai/adapter-utils/server-utils";
const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
const SEEDED_SHARED_FILES = [
".credentials.json",
"credentials.json",
@@ -92,11 +92,14 @@ export function resolveManagedClaudeConfigSeedDir(
env: NodeJS.ProcessEnv,
companyId?: string,
): string {
const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
const instanceRoot = resolvePaperclipInstanceRootForAdapter({
homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
env,
});
return companyId
? path.resolve(paperclipHome, "instances", instanceId, "companies", companyId, "claude-config-seed")
: path.resolve(paperclipHome, "instances", instanceId, "claude-config-seed");
? path.resolve(instanceRoot, "companies", companyId, "claude-config-seed")
: path.resolve(instanceRoot, "claude-config-seed");
}
export async function prepareClaudeConfigSeed(
packages/adapters/claude-local/src/server/prompt-cache.ts
+11 -9
View File
@@ -1,12 +1,13 @@
import { constants as fsConstants } from "node:fs";
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { createHash, type Hash } from "node:crypto";
import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
import { ensurePaperclipSkillSymlink, type PaperclipSkillEntry } from "@paperclipai/adapter-utils/server-utils";
const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
import {
ensurePaperclipSkillSymlink,
resolvePaperclipInstanceRootForAdapter,
type PaperclipSkillEntry,
} from "@paperclipai/adapter-utils/server-utils";
type SkillEntry = PaperclipSkillEntry;
@@ -25,12 +26,13 @@ function resolveManagedClaudePromptCacheRoot(
env: NodeJS.ProcessEnv,
companyId: string,
): string {
const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
const instanceRoot = resolvePaperclipInstanceRootForAdapter({
homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
env,
});
return path.resolve(
paperclipHome,
"instances",
instanceId,
instanceRoot,
"companies",
companyId,
"claude-prompt-cache",
packages/adapters/codex-local/src/server/codex-home.ts
+8 -5
View File
@@ -2,11 +2,11 @@ import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import type { AdapterExecutionContext } from "@paperclipai/adapter-utils";
import { resolvePaperclipInstanceRootForAdapter } from "@paperclipai/adapter-utils/server-utils";
const TRUTHY_ENV_RE = /^(1|true|yes|on)$/i;
const COPIED_SHARED_FILES = ["config.json", "config.toml", "instructions.md"] as const;
const SYMLINKED_SHARED_FILES = ["auth.json"] as const;
const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
function nonEmpty(value: string | undefined): string | null {
return typeof value === "string" && value.trim().length > 0 ? value.trim() : null;
@@ -31,11 +31,14 @@ export function resolveManagedCodexHomeDir(
env: NodeJS.ProcessEnv,
companyId?: string,
): string {
const paperclipHome = nonEmpty(env.PAPERCLIP_HOME) ?? path.resolve(os.homedir(), ".paperclip");
const instanceId = nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? DEFAULT_PAPERCLIP_INSTANCE_ID;
const instanceRoot = resolvePaperclipInstanceRootForAdapter({
homeDir: nonEmpty(env.PAPERCLIP_HOME) ?? undefined,
instanceId: nonEmpty(env.PAPERCLIP_INSTANCE_ID) ?? undefined,
env,
});
return companyId
? path.resolve(paperclipHome, "instances", instanceId, "companies", companyId, "codex-home")
: path.resolve(paperclipHome, "instances", instanceId, "codex-home");
? path.resolve(instanceRoot, "companies", companyId, "codex-home")
: path.resolve(instanceRoot, "codex-home");
}
async function ensureParentDir(target: string): Promise<void> {
packages/db/src/backup.ts
+6 -30
View File
@@ -1,7 +1,11 @@
import { existsSync, readFileSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import { formatDatabaseBackupResult, runDatabaseBackup } from "./backup-lib.js";
import {
expandHomePrefix,
resolveDefaultBackupDir,
resolvePaperclipConfigPathForInstance,
} from "@paperclipai/shared/home-paths";
type PartialConfig = {
database?: {
@@ -15,30 +19,6 @@ type PartialConfig = {
};
};
function expandHomePrefix(value: string): string {
if (value === "~") return os.homedir();
if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
return value;
}
function resolvePaperclipHomeDir(): string {
const envHome = process.env.PAPERCLIP_HOME?.trim();
if (envHome) return path.resolve(expandHomePrefix(envHome));
return path.resolve(os.homedir(), ".paperclip");
}
function resolvePaperclipInstanceId(): string {
const raw = process.env.PAPERCLIP_INSTANCE_ID?.trim() || "default";
if (!/^[a-zA-Z0-9_-]+$/.test(raw)) {
throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
}
return raw;
}
function resolveDefaultConfigPath(): string {
return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "config.json");
}
function readConfig(configPath: string): PartialConfig | null {
if (!existsSync(configPath)) return null;
try {
@@ -72,10 +52,6 @@ function resolveConnectionString(config: PartialConfig | null): string {
return `postgres://paperclip:paperclip@127.0.0.1:${port}/paperclip`;
}
function resolveDefaultBackupDir(): string {
return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "data", "backups");
}
function resolveBackupDir(config: PartialConfig | null): string {
const raw = config?.database?.backup?.dir;
if (typeof raw === "string" && raw.trim().length > 0) {
@@ -89,7 +65,7 @@ function resolveRetentionDays(config: PartialConfig | null): number {
}
async function main() {
const configPath = resolveDefaultConfigPath();
const configPath = resolvePaperclipConfigPathForInstance();
const config = readConfig(configPath);
const connectionString = resolveConnectionString(config);
const backupDir = resolveBackupDir(config);
packages/db/src/runtime-config.test.ts
+21
View File
@@ -105,4 +105,25 @@ describe("resolveDatabaseTarget", () => {
source: "embedded-postgres@55444",
});
});
it("uses the instance root for a fresh default embedded postgres target", () => {
const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-home-"));
const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-db-cwd-"));
process.chdir(cwd);
process.env.PAPERCLIP_HOME = home;
delete process.env.PAPERCLIP_CONFIG;
delete process.env.PAPERCLIP_INSTANCE_ID;
delete process.env.DATABASE_URL;
const target = resolveDatabaseTarget();
expect(target).toMatchObject({
mode: "embedded-postgres",
dataDir: path.join(home, "instances", "default", "db"),
port: 54329,
source: "embedded-postgres@54329",
configPath: path.join(home, "instances", "default", "config.json"),
envPath: path.join(home, "instances", "default", ".env"),
});
});
});
packages/db/src/runtime-config.ts
+8 -39
View File
@@ -1,11 +1,13 @@
import { existsSync, readFileSync } from "node:fs";
import os from "node:os";
import path from "node:path";
import {
expandHomePrefix,
resolveDefaultEmbeddedPostgresDir,
resolvePaperclipConfigPathForInstance,
resolvePaperclipEnvPathForConfig,
} from "@paperclipai/shared/home-paths";
const DEFAULT_INSTANCE_ID = "default";
const CONFIG_BASENAME = "config.json";
const ENV_BASENAME = ".env";
const INSTANCE_ID_RE = /^[a-zA-Z0-9_-]+$/;
type PartialConfig = {
database?: {
@@ -35,39 +37,6 @@ export type ResolvedDatabaseTarget =
envPath: string;
};
function expandHomePrefix(value: string): string {
if (value === "~") return os.homedir();
if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
return value;
}
function resolvePaperclipHomeDir(): string {
const envHome = process.env.PAPERCLIP_HOME?.trim();
if (envHome) return path.resolve(expandHomePrefix(envHome));
return path.resolve(os.homedir(), ".paperclip");
}
function resolvePaperclipInstanceId(): string {
const raw = process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_INSTANCE_ID;
if (!INSTANCE_ID_RE.test(raw)) {
throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
}
return raw;
}
function resolveDefaultConfigPath(): string {
return path.resolve(
resolvePaperclipHomeDir(),
"instances",
resolvePaperclipInstanceId(),
CONFIG_BASENAME,
);
}
function resolveDefaultEmbeddedPostgresDir(): string {
return path.resolve(resolvePaperclipHomeDir(), "instances", resolvePaperclipInstanceId(), "db");
}
function resolveHomeAwarePath(value: string): string {
return path.resolve(expandHomePrefix(value));
}
@@ -89,11 +58,11 @@ function resolvePaperclipConfigPath(): string {
if (process.env.PAPERCLIP_CONFIG?.trim()) {
return path.resolve(process.env.PAPERCLIP_CONFIG.trim());
}
return findConfigFileFromAncestors(process.cwd()) ?? resolveDefaultConfigPath();
return findConfigFileFromAncestors(process.cwd()) ?? resolvePaperclipConfigPathForInstance();
}
function resolvePaperclipEnvPath(configPath: string): string {
return path.resolve(path.dirname(configPath), ENV_BASENAME);
return resolvePaperclipEnvPathForConfig(configPath);
}
function parseEnvFile(contents: string): Record<string, string> {
packages/plugins/sdk/src/host-client-factory.ts
+26
View File
@@ -98,6 +98,7 @@ export interface HostServices {
list(params: WorkerToHostMethods["localFolders.list"][0]): Promise<WorkerToHostMethods["localFolders.list"][1]>;
readText(params: WorkerToHostMethods["localFolders.readText"][0]): Promise<WorkerToHostMethods["localFolders.readText"][1]>;
writeTextAtomic(params: WorkerToHostMethods["localFolders.writeTextAtomic"][0]): Promise<WorkerToHostMethods["localFolders.writeTextAtomic"][1]>;
deleteFile(params: WorkerToHostMethods["localFolders.deleteFile"][0]): Promise<WorkerToHostMethods["localFolders.deleteFile"][1]>;
};
/** Provides `state.get`, `state.set`, `state.delete`. */
@@ -189,6 +190,13 @@ export interface HostServices {
managedRun(params: WorkerToHostMethods["routines.managed.run"][0]): Promise<WorkerToHostMethods["routines.managed.run"][1]>;
};
/** Provides `skills.managed.*`. */
skills: {
managedGet(params: WorkerToHostMethods["skills.managed.get"][0]): Promise<WorkerToHostMethods["skills.managed.get"][1]>;
managedReconcile(params: WorkerToHostMethods["skills.managed.reconcile"][0]): Promise<WorkerToHostMethods["skills.managed.reconcile"][1]>;
managedReset(params: WorkerToHostMethods["skills.managed.reset"][0]): Promise<WorkerToHostMethods["skills.managed.reset"][1]>;
};
/** Provides issue read/write, relation, checkout, wakeup, summary, comment methods. */
issues: {
list(params: WorkerToHostMethods["issues.list"][0]): Promise<WorkerToHostMethods["issues.list"][1]>;
@@ -313,6 +321,7 @@ const METHOD_CAPABILITY_MAP: Record<WorkerToHostMethodName, PluginCapability | n
"localFolders.list": "local.folders",
"localFolders.readText": "local.folders",
"localFolders.writeTextAtomic": "local.folders",
"localFolders.deleteFile": "local.folders",
// State
"state.get": "plugin.state.read",
@@ -367,6 +376,9 @@ const METHOD_CAPABILITY_MAP: Record<WorkerToHostMethodName, PluginCapability | n
"routines.managed.reset": "routines.managed",
"routines.managed.update": "routines.managed",
"routines.managed.run": "routines.managed",
"skills.managed.get": "skills.managed",
"skills.managed.reconcile": "skills.managed",
"skills.managed.reset": "skills.managed",
// Issues
"issues.list": "issues.read",
@@ -501,6 +513,9 @@ export function createHostClientHandlers(
"localFolders.writeTextAtomic": gated("localFolders.writeTextAtomic", async (params) => {
return services.localFolders.writeTextAtomic(params);
}),
"localFolders.deleteFile": gated("localFolders.deleteFile", async (params) => {
return services.localFolders.deleteFile(params);
}),
// State
"state.get": gated("state.get", async (params) => {
@@ -620,6 +635,17 @@ export function createHostClientHandlers(
return services.routines.managedRun(params);
}),
// Skills
"skills.managed.get": gated("skills.managed.get", async (params) => {
return services.skills.managedGet(params);
}),
"skills.managed.reconcile": gated("skills.managed.reconcile", async (params) => {
return services.skills.managedReconcile(params);
}),
"skills.managed.reset": gated("skills.managed.reset", async (params) => {
return services.skills.managedReset(params);
}),
// Issues
"issues.list": gated("issues.list", async (params) => {
return services.issues.list(params);
packages/plugins/sdk/src/index.ts
+5
View File
@@ -197,6 +197,7 @@ export type {
PluginStateClient,
PluginEntitiesClient,
PluginProjectsClient,
PluginSkillsClient,
PluginCompaniesClient,
PluginIssuesClient,
PluginIssueMutationActor,
@@ -268,6 +269,10 @@ export type {
PluginManagedProjectResolution,
PluginManagedRoutineDeclaration,
PluginManagedRoutineResolution,
PluginManagedSkillDeclaration,
PluginManagedSkillFileDeclaration,
PluginManagedSkillResolution,
CompanySkill,
PluginManagedResourceKind,
PluginManagedResourceRef,
PluginUiSlotDeclaration,
packages/plugins/sdk/src/protocol.ts
+19 -1
View File
@@ -27,11 +27,13 @@ import type {
IssueComment,
IssueDocument,
IssueDocumentSummary,
IssueAssigneeAdapterOverrides,
IssueThreadInteraction,
CreateIssueThreadInteraction,
PluginManagedAgentResolution,
PluginManagedProjectResolution,
PluginManagedRoutineResolution,
PluginManagedSkillResolution,
Routine,
RoutineRun,
Agent,
@@ -611,6 +613,10 @@ export interface WorkerToHostMethods {
},
result: PluginLocalFolderStatus,
];
"localFolders.deleteFile": [
params: { companyId: string; folderKey: string; relativePath: string },
result: PluginLocalFolderStatus,
];
// State
"state.get": [
@@ -821,6 +827,18 @@ export interface WorkerToHostMethods {
},
result: RoutineRun,
];
"skills.managed.get": [
params: { skillKey: string; companyId: string },
result: PluginManagedSkillResolution,
];
"skills.managed.reconcile": [
params: { skillKey: string; companyId: string },
result: PluginManagedSkillResolution,
];
"skills.managed.reset": [
params: { skillKey: string; companyId: string },
result: PluginManagedSkillResolution,
];
// Issues
"issues.list": [
@@ -852,12 +870,12 @@ export interface WorkerToHostMethods {
title: string;
description?: string;
status?: string;
workMode?: string;
priority?: string;
assigneeAgentId?: string;
assigneeUserId?: string | null;
requestDepth?: number;
billingCode?: string | null;
assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
surfaceVisibility?: string | null;
originKind?: string | null;
originId?: string | null;
packages/plugins/sdk/src/testing.ts
+289 -38
View File
@@ -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,
packages/plugins/sdk/src/types.ts
+26 -2
View File
@@ -22,6 +22,7 @@ import type {
IssueDocument,
IssueDocumentSummary,
IssueRelationIssueSummary,
IssueAssigneeAdapterOverrides,
IssueThreadInteraction,
SuggestTasksInteraction,
AskUserQuestionsInteraction,
@@ -32,6 +33,8 @@ import type {
PluginManagedAgentResolution,
PluginManagedProjectResolution,
PluginManagedRoutineResolution,
PluginManagedSkillResolution,
CompanySkill,
Routine,
RoutineRun,
Agent,
@@ -54,6 +57,10 @@ export type {
PluginManagedProjectResolution,
PluginManagedRoutineDeclaration,
PluginManagedRoutineResolution,
PluginManagedSkillDeclaration,
PluginManagedSkillFileDeclaration,
PluginManagedSkillResolution,
CompanySkill,
Routine,
RoutineRun,
PluginLocalFolderDeclaration,
@@ -450,6 +457,8 @@ export interface PluginLocalFoldersClient {
relativePath: string,
contents: string,
): Promise<PluginLocalFolderStatus>;
/** Delete a file below a configured folder after containment checks. Missing files are treated as already deleted. */
deleteFile(companyId: string, folderKey: string, relativePath: string): Promise<PluginLocalFolderStatus>;
}
/**
@@ -840,6 +849,19 @@ export interface PluginRoutinesClient {
};
}
/**
* `ctx.skills` — resolve and reconcile plugin-managed company skills.
*
* Requires `skills.managed` capability.
*/
export interface PluginSkillsClient {
managed: {
get(skillKey: string, companyId: string): Promise<PluginManagedSkillResolution>;
reconcile(skillKey: string, companyId: string): Promise<PluginManagedSkillResolution>;
reset(skillKey: string, companyId: string): Promise<PluginManagedSkillResolution>;
};
}
/**
* `ctx.data` — register `getData` handlers that back `usePluginData()` in the
* plugin's frontend components.
@@ -1257,12 +1279,12 @@ export interface PluginIssuesClient {
title: string;
description?: string;
status?: Issue["status"];
workMode?: Issue["workMode"];
priority?: Issue["priority"];
assigneeAgentId?: string;
assigneeUserId?: string | null;
requestDepth?: number;
billingCode?: string | null;
assigneeAdapterOverrides?: IssueAssigneeAdapterOverrides | null;
surfaceVisibility?: IssueSurfaceVisibility;
originKind?: PluginIssueOriginKind;
originId?: string | null;
@@ -1281,7 +1303,6 @@ export interface PluginIssuesClient {
| "title"
| "description"
| "status"
| "workMode"
| "priority"
| "assigneeAgentId"
| "assigneeUserId"
@@ -1624,6 +1645,9 @@ export interface PluginContext {
/** Resolve and reconcile plugin-managed routines. Requires `routines.managed`. */
routines: PluginRoutinesClient;
/** Resolve and reconcile plugin-managed company skills. Requires `skills.managed`. */
skills: PluginSkillsClient;
/** Read company metadata. Requires `companies.read`. */
companies: PluginCompaniesClient;
packages/plugins/sdk/src/worker-rpc-host.ts
+19 -1
View File
@@ -430,6 +430,10 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
contents,
});
},
async deleteFile(companyId: string, folderKey: string, relativePath: string) {
return callHost("localFolders.deleteFile", { companyId, folderKey, relativePath });
},
},
events: {
@@ -671,6 +675,20 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
},
},
skills: {
managed: {
async get(skillKey: string, companyId: string) {
return callHost("skills.managed.get", { skillKey, companyId });
},
async reconcile(skillKey: string, companyId: string) {
return callHost("skills.managed.reconcile", { skillKey, companyId });
},
async reset(skillKey: string, companyId: string) {
return callHost("skills.managed.reset", { skillKey, companyId });
},
},
},
companies: {
async list(input) {
return callHost("companies.list", {
@@ -714,12 +732,12 @@ export function startWorkerRpcHost(options: WorkerRpcHostOptions): WorkerRpcHost
title: input.title,
description: input.description,
status: input.status,
workMode: input.workMode,
priority: input.priority,
assigneeAgentId: input.assigneeAgentId,
assigneeUserId: input.assigneeUserId,
requestDepth: input.requestDepth,
billingCode: input.billingCode,
assigneeAdapterOverrides: input.assigneeAdapterOverrides,
surfaceVisibility: input.surfaceVisibility,
originKind: input.originKind,
originId: input.originId,
packages/shared/src/config-schema.test.ts
+27
View File
@@ -0,0 +1,27 @@
import { describe, expect, it } from "vitest";
import { paperclipConfigSchema } from "./config-schema.js";
describe("paperclip config schema", () => {
it("defaults omitted runtime paths to legacy instance-root locations", () => {
const parsed = paperclipConfigSchema.parse({
$meta: {
version: 1,
updatedAt: "2026-05-10T00:00:00.000Z",
source: "configure",
},
database: {
mode: "embedded-postgres",
},
logging: {
mode: "file",
},
server: {},
});
expect(parsed.database.embeddedPostgresDataDir).toBe("~/.paperclip/instances/default/db");
expect(parsed.database.backup.dir).toBe("~/.paperclip/instances/default/data/backups");
expect(parsed.logging.logDir).toBe("~/.paperclip/instances/default/logs");
expect(parsed.storage.localDisk.baseDir).toBe("~/.paperclip/instances/default/data/storage");
expect(parsed.secrets.localEncrypted.keyFilePath).toBe("~/.paperclip/instances/default/secrets/master.key");
});
});
packages/shared/src/constants.ts
+1
View File
@@ -715,6 +715,7 @@ export const PLUGIN_CAPABILITIES = [
"issue.documents.write",
"projects.managed",
"routines.managed",
"skills.managed",
"agents.pause",
"agents.resume",
"agents.invoke",
packages/shared/src/home-paths.test.ts
+36
View File
@@ -0,0 +1,36 @@
import fs from "node:fs";
import os from "node:os";
import path from "node:path";
import { afterEach, describe, expect, it } from "vitest";
import {
resolveDefaultBackupDir,
resolveDefaultEmbeddedPostgresDir,
resolveDefaultLogsDir,
resolveDefaultSecretsKeyFilePath,
resolveDefaultStorageDir,
resolvePaperclipConfigPathForInstance,
resolvePaperclipInstanceRoot,
} from "./home-paths.js";
const ORIGINAL_ENV = { ...process.env };
afterEach(() => {
process.env = { ...ORIGINAL_ENV };
});
describe("home path resolution", () => {
it("resolves config and runtime data directly under the instance root", () => {
const home = fs.mkdtempSync(path.join(os.tmpdir(), "paperclip-home-paths-"));
process.env.PAPERCLIP_HOME = home;
delete process.env.PAPERCLIP_INSTANCE_ID;
const instanceRoot = path.join(home, "instances", "default");
expect(resolvePaperclipInstanceRoot()).toBe(instanceRoot);
expect(resolvePaperclipConfigPathForInstance()).toBe(path.join(instanceRoot, "config.json"));
expect(resolveDefaultEmbeddedPostgresDir()).toBe(path.join(instanceRoot, "db"));
expect(resolveDefaultBackupDir()).toBe(path.join(instanceRoot, "data", "backups"));
expect(resolveDefaultLogsDir()).toBe(path.join(instanceRoot, "logs"));
expect(resolveDefaultStorageDir()).toBe(path.join(instanceRoot, "data", "storage"));
expect(resolveDefaultSecretsKeyFilePath()).toBe(path.join(instanceRoot, "secrets", "master.key"));
});
});
packages/shared/src/home-paths.ts
+92
View File
@@ -0,0 +1,92 @@
import os from "node:os";
import path from "node:path";
export const DEFAULT_PAPERCLIP_INSTANCE_ID = "default";
export const PAPERCLIP_CONFIG_BASENAME = "config.json";
export const PAPERCLIP_ENV_FILENAME = ".env";
const PATH_SEGMENT_RE = /^[a-zA-Z0-9_-]+$/;
export function expandHomePrefix(value: string): string {
if (value === "~") return os.homedir();
if (value.startsWith("~/")) return path.resolve(os.homedir(), value.slice(2));
return value;
}
export function resolvePaperclipHomeDir(homeOverride?: string): string {
const raw = homeOverride?.trim() || process.env.PAPERCLIP_HOME?.trim();
if (raw) return path.resolve(expandHomePrefix(raw));
return path.resolve(os.homedir(), ".paperclip");
}
export function resolvePaperclipInstanceId(instanceIdOverride?: string): string {
const raw = instanceIdOverride?.trim() || process.env.PAPERCLIP_INSTANCE_ID?.trim() || DEFAULT_PAPERCLIP_INSTANCE_ID;
if (!PATH_SEGMENT_RE.test(raw)) {
throw new Error(`Invalid PAPERCLIP_INSTANCE_ID '${raw}'.`);
}
return raw;
}
export function resolvePaperclipInstanceRoot(input: {
homeDir?: string;
instanceId?: string;
} = {}): string {
return path.resolve(resolvePaperclipHomeDir(input.homeDir), "instances", resolvePaperclipInstanceId(input.instanceId));
}
export function resolvePaperclipInstanceConfigPath(input: {
homeDir?: string;
instanceId?: string;
} = {}): string {
return path.resolve(resolvePaperclipInstanceRoot(input), PAPERCLIP_CONFIG_BASENAME);
}
export function resolvePaperclipConfigPathForInstance(input: {
homeDir?: string;
instanceId?: string;
} = {}): string {
return resolvePaperclipInstanceConfigPath(input);
}
export function resolvePaperclipEnvPathForConfig(configPath: string): string {
return path.resolve(path.dirname(configPath), PAPERCLIP_ENV_FILENAME);
}
export function resolveDefaultEmbeddedPostgresDir(input: {
homeDir?: string;
instanceId?: string;
} = {}): string {
return path.resolve(resolvePaperclipInstanceRoot(input), "db");
}
export function resolveDefaultLogsDir(input: {
homeDir?: string;
instanceId?: string;
} = {}): string {
return path.resolve(resolvePaperclipInstanceRoot(input), "logs");
}
export function resolveDefaultSecretsKeyFilePath(input: {
homeDir?: string;
instanceId?: string;
} = {}): string {
return path.resolve(resolvePaperclipInstanceRoot(input), "secrets", "master.key");
}
export function resolveDefaultStorageDir(input: {
homeDir?: string;
instanceId?: string;
} = {}): string {
return path.resolve(resolvePaperclipInstanceRoot(input), "data", "storage");
}
export function resolveDefaultBackupDir(input: {
homeDir?: string;
instanceId?: string;
} = {}): string {
return path.resolve(resolvePaperclipInstanceRoot(input), "data", "backups");
}
export function resolveHomeAwarePath(value: string): string {
return path.resolve(expandHomePrefix(value));
}
packages/shared/src/index.ts
+3
View File
@@ -581,10 +581,13 @@ export type {
PluginManagedAgentDeclaration,
PluginManagedProjectDeclaration,
PluginManagedRoutineDeclaration,
PluginManagedSkillDeclaration,
PluginManagedSkillFileDeclaration,
PluginLocalFolderDeclaration,
PluginManagedAgentResolution,
PluginManagedProjectResolution,
PluginManagedRoutineResolution,
PluginManagedSkillResolution,
PluginManagedResourceKind,
PluginManagedResourceRef,
PluginUiSlotDeclaration,
packages/shared/src/types/index.ts
+3
View File
@@ -373,10 +373,13 @@ export type {
PluginManagedAgentDeclaration,
PluginManagedProjectDeclaration,
PluginManagedRoutineDeclaration,
PluginManagedSkillDeclaration,
PluginManagedSkillFileDeclaration,
PluginLocalFolderDeclaration,
PluginManagedAgentResolution,
PluginManagedProjectResolution,
PluginManagedRoutineResolution,
PluginManagedSkillResolution,
PluginManagedResourceKind,
PluginManagedResourceRef,
PluginUiSlotDeclaration,
packages/shared/src/types/plugin.ts
+48 -1
View File
@@ -27,6 +27,7 @@ import type {
IssueSurfaceVisibility,
} from "../constants.js";
import type { Agent } from "./agent.js";
import type { CompanySkill } from "./company-skill.js";
import type { Project } from "./project.js";
import type { Routine, RoutineTrigger, RoutineVariable } from "./routine.js";
@@ -164,6 +165,7 @@ export interface PluginManagedAgentDeclaration {
instructions?: {
entryFile?: string;
content?: string;
files?: Record<string, string>;
assetPath?: string;
};
}
@@ -208,7 +210,33 @@ export interface PluginManagedProjectDeclaration {
settings?: Record<string, unknown>;
}
export type PluginManagedResourceKind = "agent" | "project" | "routine";
export interface PluginManagedSkillFileDeclaration {
/** Relative path inside the skill folder, for example `references/guide.md`. */
path: string;
/** File contents written when the skill is installed or reset. */
content: string;
}
/**
* Declares a company skill that a plugin can install into each company's
* skills library and later resolve by stable key.
*/
export interface PluginManagedSkillDeclaration {
/** Stable identifier for this managed skill, unique within the plugin. */
skillKey: string;
/** Suggested visible skill name. */
displayName: string;
/** Suggested skill slug. Defaults to `skillKey`. */
slug?: string;
/** Suggested skill description. */
description?: string | null;
/** Full `SKILL.md` contents. Defaults to generated markdown from display metadata. */
markdown?: string;
/** Additional files installed with the skill. */
files?: PluginManagedSkillFileDeclaration[];
}
export type PluginManagedResourceKind = "agent" | "project" | "routine" | "skill";
export interface PluginManagedResourceRef {
pluginKey?: string;
@@ -258,6 +286,10 @@ export interface PluginManagedAgentResolution {
agent: Agent | null;
status: "missing" | "resolved" | "created" | "relinked" | "reset";
approvalId?: string | null;
defaultDrift?: {
entryFile: string;
changedFiles: string[];
} | null;
}
export interface PluginManagedProjectResolution {
@@ -281,6 +313,19 @@ export interface PluginManagedRoutineResolution {
missingRefs?: PluginManagedResourceRef[];
}
export interface PluginManagedSkillResolution {
pluginKey: string;
resourceKind: "skill";
resourceKey: string;
companyId: string;
skillId: string | null;
skill: CompanySkill | null;
status: "missing" | "resolved" | "created" | "relinked" | "reset";
defaultDrift?: {
changedFiles: string[];
} | null;
}
/**
* Declares a UI extension slot the plugin fills with a React component.
*
@@ -496,6 +541,8 @@ export interface PaperclipPluginManifestV1 {
projects?: PluginManagedProjectDeclaration[];
/** Suggested company-scoped routines this plugin can provision and resolve by stable key. */
routines?: PluginManagedRoutineDeclaration[];
/** Suggested company skills this plugin can install and resolve by stable key. */
skills?: PluginManagedSkillDeclaration[];
/** Trusted local folders this plugin can configure and access by stable key. */
localFolders?: PluginLocalFolderDeclaration[];
/**
packages/shared/src/validators/index.ts
+4
View File
@@ -394,6 +394,8 @@ export {
pluginLauncherRenderDeclarationSchema,
pluginLauncherDeclarationSchema,
pluginDatabaseDeclarationSchema,
pluginManagedSkillFileDeclarationSchema,
pluginManagedSkillDeclarationSchema,
pluginApiRouteDeclarationSchema,
pluginManifestV1Schema,
installPluginSchema,
@@ -413,6 +415,8 @@ export {
type PluginLauncherRenderDeclarationInput,
type PluginLauncherDeclarationInput,
type PluginDatabaseDeclarationInput,
type PluginManagedSkillFileDeclarationInput,
type PluginManagedSkillDeclarationInput,
type PluginApiRouteDeclarationInput,
type PluginManifestV1Input,
type InstallPlugin,
packages/shared/src/validators/plugin.test.ts
+36 -1
View File
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
import { PLUGIN_CAPABILITIES } from "../constants.js";
import { pluginManagedRoutineDeclarationSchema, pluginUiSlotDeclarationSchema } from "./plugin.js";
import { pluginManagedRoutineDeclarationSchema, pluginManifestV1Schema, pluginUiSlotDeclarationSchema } from "./plugin.js";
describe("plugin capability constants", () => {
it("exposes each capability once", () => {
@@ -30,6 +30,41 @@ describe("plugin managed routine validators", () => {
});
});
describe("plugin managed skill validators", () => {
const baseManifest = {
id: "paperclip.test-managed-skills",
apiVersion: 1,
version: "0.1.0",
displayName: "Managed Skills",
description: "Managed skills test plugin.",
author: "Paperclip",
categories: ["automation"],
entrypoints: { worker: "./dist/worker.js" },
} as const;
it("requires skills.managed when managed skills are declared", () => {
const parsed = pluginManifestV1Schema.safeParse({
...baseManifest,
capabilities: [],
skills: [{ skillKey: "wiki-maintainer", displayName: "Wiki Maintainer" }],
});
expect(parsed.success).toBe(false);
if (parsed.success) return;
expect(parsed.error.issues.some((issue) => issue.message.includes("skills.managed"))).toBe(true);
});
it("accepts managed skills with the skills.managed capability", () => {
const parsed = pluginManifestV1Schema.parse({
...baseManifest,
capabilities: ["skills.managed"],
skills: [{ skillKey: "wiki-maintainer", displayName: "Wiki Maintainer" }],
});
expect(parsed.skills?.[0]?.skillKey).toBe("wiki-maintainer");
});
});
describe("plugin UI slot validators", () => {
it("accepts route-scoped sidebar slots with a routePath", () => {
const parsed = pluginUiSlotDeclarationSchema.parse({
packages/shared/src/validators/plugin.ts
+60 -1
View File
@@ -151,6 +151,7 @@ export const pluginManagedAgentDeclarationSchema = z.object({
instructions: z.object({
entryFile: z.string().min(1).max(200).optional(),
content: z.string().max(200_000).optional(),
files: z.record(z.string().max(200_000)).optional(),
assetPath: z.string().min(1).max(500).optional(),
}).optional(),
});
@@ -172,7 +173,7 @@ export type PluginManagedProjectDeclarationInput = z.infer<typeof pluginManagedP
const pluginManagedResourceRefSchema = z.object({
pluginKey: z.string().min(1).max(100).optional(),
resourceKind: z.enum(["agent", "project", "routine"]),
resourceKind: z.enum(["agent", "project", "routine", "skill"]),
resourceKey: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9._:-]*$/, {
message: "resourceKey must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, colons, underscores, or hyphens",
}),
@@ -232,6 +233,41 @@ export const pluginLocalFolderDeclarationSchema = z.object({
export type PluginLocalFolderDeclarationInput = z.infer<typeof pluginLocalFolderDeclarationSchema>;
export const pluginManagedSkillFileDeclarationSchema = z.object({
path: pluginLocalFolderRelativePathSchema.refine(
(value) => value.toLowerCase() !== "skill.md",
{ message: "managed skill files cannot replace SKILL.md; use markdown for the main skill file" },
),
content: z.string().max(200_000),
});
export type PluginManagedSkillFileDeclarationInput = z.infer<typeof pluginManagedSkillFileDeclarationSchema>;
export const pluginManagedSkillDeclarationSchema = z.object({
skillKey: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9._:-]*$/, {
message: "skillKey must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, colons, underscores, or hyphens",
}),
displayName: z.string().min(1).max(100),
slug: z.string().min(1).max(100).regex(/^[a-z0-9][a-z0-9._:-]*$/, {
message: "slug must start with a lowercase alphanumeric and contain only lowercase letters, digits, dots, colons, underscores, or hyphens",
}).optional(),
description: z.string().max(2000).nullable().optional(),
markdown: z.string().max(200_000).optional(),
files: z.array(pluginManagedSkillFileDeclarationSchema).max(50).optional(),
}).superRefine((value, ctx) => {
const paths = (value.files ?? []).map((file) => file.path);
const duplicates = paths.filter((path, index) => paths.indexOf(path) !== index);
if (duplicates.length > 0) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `Duplicate managed skill file paths: ${[...new Set(duplicates)].join(", ")}`,
path: ["files"],
});
}
});
export type PluginManagedSkillDeclarationInput = z.infer<typeof pluginManagedSkillDeclarationSchema>;
/**
* Validates a {@link PluginUiSlotDeclaration} — a UI extension slot the plugin
* fills with a React component. Includes `superRefine` checks for slot-specific
@@ -589,6 +625,7 @@ export const pluginManifestV1Schema = z.object({
agents: z.array(pluginManagedAgentDeclarationSchema).optional(),
projects: z.array(pluginManagedProjectDeclarationSchema).optional(),
routines: z.array(pluginManagedRoutineDeclarationSchema).optional(),
skills: z.array(pluginManagedSkillDeclarationSchema).optional(),
localFolders: z.array(pluginLocalFolderDeclarationSchema).optional(),
launchers: z.array(pluginLauncherDeclarationSchema).optional(),
ui: z.object({
@@ -678,6 +715,16 @@ export const pluginManifestV1Schema = z.object({
}
}
if (manifest.skills && manifest.skills.length > 0) {
if (!manifest.capabilities.includes("skills.managed")) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: "Capability 'skills.managed' is required when managed skills are declared",
path: ["capabilities"],
});
}
}
if (manifest.localFolders && manifest.localFolders.length > 0) {
if (!manifest.capabilities.includes("local.folders")) {
ctx.addIssue({
@@ -871,6 +918,18 @@ export const pluginManifestV1Schema = z.object({
}
}
if (manifest.skills) {
const skillKeys = manifest.skills.map((skill) => skill.skillKey);
const duplicates = skillKeys.filter((key, i) => skillKeys.indexOf(key) !== i);
if (duplicates.length > 0) {
ctx.addIssue({
code: z.ZodIssueCode.custom,
message: `Duplicate managed skill keys: ${[...new Set(duplicates)].join(", ")}`,
path: ["skills"],
});
}
}
// UI slot ids must be unique within the plugin (namespaced at runtime)
if (manifest.ui) {
if (manifest.ui.slots) {