aevgarik/paperclip
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(core): merge backup core changes with post-split functionality

Browse Source
This commit is contained in:
Dotta
2026-03-02 16:43:59 -06:00
parent 7642743e62
commit 83be94361c
25 changed files with 1125 additions and 46 deletions
Download Patch File Download Diff File Expand all files Collapse all files

407
cli/src/commands/client/company.ts
View File

@@ -1,5 +1,15 @@
import { Command } from "commander";
import type { Company } from "@paperclip/shared";
import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
import path from "node:path";
import type {
Company,
CompanyPortabilityExportResult,
CompanyPortabilityInclude,
CompanyPortabilityManifest,
CompanyPortabilityPreviewResult,
CompanyPortabilityImportResult,
} from "@paperclip/shared";
import { ApiRequestError } from "../../client/http.js";
import {
addCommonClientOptions,
formatInlineRecord,
@@ -10,6 +20,185 @@ import {
} from "./common.js";
interface CompanyCommandOptions extends BaseClientOptions {}
type CompanyDeleteSelectorMode = "auto" | "id" | "prefix";
type CompanyImportTargetMode = "new" | "existing";
type CompanyCollisionMode = "rename" | "skip" | "replace";
interface CompanyDeleteOptions extends BaseClientOptions {
by?: CompanyDeleteSelectorMode;
yes?: boolean;
confirm?: string;
}
interface CompanyExportOptions extends BaseClientOptions {
out?: string;
include?: string;
}
interface CompanyImportOptions extends BaseClientOptions {
from?: string;
include?: string;
target?: CompanyImportTargetMode;
companyId?: string;
newCompanyName?: string;
agents?: string;
collision?: CompanyCollisionMode;
dryRun?: boolean;
}
function isUuidLike(value: string): boolean {
return /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
}
function normalizeSelector(input: string): string {
return input.trim();
}
function parseInclude(input: string | undefined): CompanyPortabilityInclude {
if (!input || !input.trim()) return { company: true, agents: true };
const values = input.split(",").map((part) => part.trim().toLowerCase()).filter(Boolean);
const include = {
company: values.includes("company"),
agents: values.includes("agents"),
};
if (!include.company && !include.agents) {
throw new Error("Invalid --include value. Use one or both of: company,agents");
}
return include;
}
function parseAgents(input: string | undefined): "all" | string[] {
if (!input || !input.trim()) return "all";
const normalized = input.trim().toLowerCase();
if (normalized === "all") return "all";
const values = input.split(",").map((part) => part.trim()).filter(Boolean);
if (values.length === 0) return "all";
return Array.from(new Set(values));
}
function isHttpUrl(input: string): boolean {
return /^https?:\/\//i.test(input.trim());
}
function isGithubUrl(input: string): boolean {
return /^https?:\/\/github\.com\//i.test(input.trim());
}
async function resolveInlineSourceFromPath(inputPath: string): Promise<{
manifest: CompanyPortabilityManifest;
files: Record<string, string>;
}> {
const resolved = path.resolve(inputPath);
const resolvedStat = await stat(resolved);
const manifestPath = resolvedStat.isDirectory()
? path.join(resolved, "paperclip.manifest.json")
: resolved;
const manifestBaseDir = path.dirname(manifestPath);
const manifestRaw = await readFile(manifestPath, "utf8");
const manifest = JSON.parse(manifestRaw) as CompanyPortabilityManifest;
const files: Record<string, string> = {};
if (manifest.company?.path) {
const companyPath = manifest.company.path.replace(/\\/g, "/");
files[companyPath] = await readFile(path.join(manifestBaseDir, companyPath), "utf8");
}
for (const agent of manifest.agents ?? []) {
const agentPath = agent.path.replace(/\\/g, "/");
files[agentPath] = await readFile(path.join(manifestBaseDir, agentPath), "utf8");
}
return { manifest, files };
}
async function writeExportToFolder(outDir: string, exported: CompanyPortabilityExportResult): Promise<void> {
const root = path.resolve(outDir);
await mkdir(root, { recursive: true });
const manifestPath = path.join(root, "paperclip.manifest.json");
await writeFile(manifestPath, JSON.stringify(exported.manifest, null, 2), "utf8");
for (const [relativePath, content] of Object.entries(exported.files)) {
const normalized = relativePath.replace(/\\/g, "/");
const filePath = path.join(root, normalized);
await mkdir(path.dirname(filePath), { recursive: true });
await writeFile(filePath, content, "utf8");
}
}
function matchesPrefix(company: Company, selector: string): boolean {
return company.issuePrefix.toUpperCase() === selector.toUpperCase();
}
export function resolveCompanyForDeletion(
companies: Company[],
selectorRaw: string,
by: CompanyDeleteSelectorMode = "auto",
): Company {
const selector = normalizeSelector(selectorRaw);
if (!selector) {
throw new Error("Company selector is required.");
}
const idMatch = companies.find((company) => company.id === selector);
const prefixMatch = companies.find((company) => matchesPrefix(company, selector));
if (by === "id") {
if (!idMatch) {
throw new Error(`No company found by ID '${selector}'.`);
}
return idMatch;
}
if (by === "prefix") {
if (!prefixMatch) {
throw new Error(`No company found by shortname/prefix '${selector}'.`);
}
return prefixMatch;
}
if (idMatch && prefixMatch && idMatch.id !== prefixMatch.id) {
throw new Error(
`Selector '${selector}' is ambiguous (matches both an ID and a shortname). Re-run with --by id or --by prefix.`,
);
}
if (idMatch) return idMatch;
if (prefixMatch) return prefixMatch;
throw new Error(
`No company found for selector '${selector}'. Use company ID or issue prefix (for example PAP).`,
);
}
export function assertDeleteConfirmation(company: Company, opts: CompanyDeleteOptions): void {
if (!opts.yes) {
throw new Error("Deletion requires --yes.");
}
const confirm = opts.confirm?.trim();
if (!confirm) {
throw new Error(
"Deletion requires --confirm <value> where value matches the company ID or issue prefix.",
);
}
const confirmsById = confirm === company.id;
const confirmsByPrefix = confirm.toUpperCase() === company.issuePrefix.toUpperCase();
if (!confirmsById && !confirmsByPrefix) {
throw new Error(
`Confirmation '${confirm}' does not match target company. Expected ID '${company.id}' or prefix '${company.issuePrefix}'.`,
);
}
}
function assertDeleteFlags(opts: CompanyDeleteOptions): void {
if (!opts.yes) {
throw new Error("Deletion requires --yes.");
}
if (!opts.confirm?.trim()) {
throw new Error(
"Deletion requires --confirm <value> where value matches the company ID or issue prefix.",
);
}
}
export function registerCompanyCommands(program: Command): void {
const company = program.command("company").description("Company operations");
@@ -64,4 +253,220 @@ export function registerCompanyCommands(program: Command): void {
}
}),
);
addCommonClientOptions(
company
.command("export")
.description("Export a company into portable manifest + markdown files")
.argument("<companyId>", "Company ID")
.requiredOption("--out <path>", "Output directory")
.option("--include <values>", "Comma-separated include set: company,agents", "company,agents")
.action(async (companyId: string, opts: CompanyExportOptions) => {
try {
const ctx = resolveCommandContext(opts);
const include = parseInclude(opts.include);
const exported = await ctx.api.post<CompanyPortabilityExportResult>(
`/api/companies/${companyId}/export`,
{ include },
);
if (!exported) {
throw new Error("Export request returned no data");
}
await writeExportToFolder(opts.out!, exported);
printOutput(
{
ok: true,
out: path.resolve(opts.out!),
filesWritten: Object.keys(exported.files).length + 1,
warningCount: exported.warnings.length,
},
{ json: ctx.json },
);
if (!ctx.json && exported.warnings.length > 0) {
for (const warning of exported.warnings) {
console.log(`warning=${warning}`);
}
}
} catch (err) {
handleCommandError(err);
}
}),
);
addCommonClientOptions(
company
.command("import")
.description("Import a portable company package from local path, URL, or GitHub")
.requiredOption("--from <pathOrUrl>", "Source path or URL")
.option("--include <values>", "Comma-separated include set: company,agents", "company,agents")
.option("--target <mode>", "Target mode: new | existing")
.option("-C, --company-id <id>", "Existing target company ID")
.option("--new-company-name <name>", "Name override for --target new")
.option("--agents <list>", "Comma-separated agent slugs to import, or all", "all")
.option("--collision <mode>", "Collision strategy: rename | skip | replace", "rename")
.option("--dry-run", "Run preview only without applying", false)
.action(async (opts: CompanyImportOptions) => {
try {
const ctx = resolveCommandContext(opts);
const from = (opts.from ?? "").trim();
if (!from) {
throw new Error("--from is required");
}
const include = parseInclude(opts.include);
const agents = parseAgents(opts.agents);
const collision = (opts.collision ?? "rename").toLowerCase() as CompanyCollisionMode;
if (!["rename", "skip", "replace"].includes(collision)) {
throw new Error("Invalid --collision value. Use: rename, skip, replace");
}
const inferredTarget = opts.target ?? (opts.companyId || ctx.companyId ? "existing" : "new");
const target = inferredTarget.toLowerCase() as CompanyImportTargetMode;
if (!["new", "existing"].includes(target)) {
throw new Error("Invalid --target value. Use: new | existing");
}
const existingTargetCompanyId = opts.companyId?.trim() || ctx.companyId;
const targetPayload =
target === "existing"
? {
mode: "existing_company" as const,
companyId: existingTargetCompanyId,
}
: {
mode: "new_company" as const,
newCompanyName: opts.newCompanyName?.trim() || null,
};
if (targetPayload.mode === "existing_company" && !targetPayload.companyId) {
throw new Error("Target existing company requires --company-id (or context default companyId).");
}
let sourcePayload:
| { type: "inline"; manifest: CompanyPortabilityManifest; files: Record<string, string> }
| { type: "url"; url: string }
| { type: "github"; url: string };
if (isHttpUrl(from)) {
sourcePayload = isGithubUrl(from)
? { type: "github", url: from }
: { type: "url", url: from };
} else {
const inline = await resolveInlineSourceFromPath(from);
sourcePayload = {
type: "inline",
manifest: inline.manifest,
files: inline.files,
};
}
const payload = {
source: sourcePayload,
include,
target: targetPayload,
agents,
collisionStrategy: collision,
};
if (opts.dryRun) {
const preview = await ctx.api.post<CompanyPortabilityPreviewResult>(
"/api/companies/import/preview",
payload,
);
printOutput(preview, { json: ctx.json });
return;
}
const imported = await ctx.api.post<CompanyPortabilityImportResult>("/api/companies/import", payload);
printOutput(imported, { json: ctx.json });
} catch (err) {
handleCommandError(err);
}
}),
);
addCommonClientOptions(
company
.command("delete")
.description("Delete a company by ID or shortname/prefix (destructive)")
.argument("<selector>", "Company ID or issue prefix (for example PAP)")
.option(
"--by <mode>",
"Selector mode: auto | id | prefix",
"auto",
)
.option("--yes", "Required safety flag to confirm destructive action", false)
.option(
"--confirm <value>",
"Required safety value: target company ID or shortname/prefix",
)
.action(async (selector: string, opts: CompanyDeleteOptions) => {
try {
const by = (opts.by ?? "auto").trim().toLowerCase() as CompanyDeleteSelectorMode;
if (!["auto", "id", "prefix"].includes(by)) {
throw new Error(`Invalid --by mode '${opts.by}'. Expected one of: auto, id, prefix.`);
}
const ctx = resolveCommandContext(opts);
const normalizedSelector = normalizeSelector(selector);
assertDeleteFlags(opts);
let target: Company | null = null;
const shouldTryIdLookup = by === "id" || (by === "auto" && isUuidLike(normalizedSelector));
if (shouldTryIdLookup) {
const byId = await ctx.api.get<Company>(`/api/companies/${normalizedSelector}`, { ignoreNotFound: true });
if (byId) {
target = byId;
} else if (by === "id") {
throw new Error(`No company found by ID '${normalizedSelector}'.`);
}
}
if (!target && ctx.companyId) {
const scoped = await ctx.api.get<Company>(`/api/companies/${ctx.companyId}`, { ignoreNotFound: true });
if (scoped) {
try {
target = resolveCompanyForDeletion([scoped], normalizedSelector, by);
} catch {
// Fallback to board-wide lookup below.
}
}
}
if (!target) {
try {
const companies = (await ctx.api.get<Company[]>("/api/companies")) ?? [];
target = resolveCompanyForDeletion(companies, normalizedSelector, by);
} catch (error) {
if (error instanceof ApiRequestError && error.status === 403 && error.message.includes("Board access required")) {
throw new Error(
"Board access is required to resolve companies across the instance. Use a company ID/prefix for your current company, or run with board authentication.",
);
}
throw error;
}
}
if (!target) {
throw new Error(`No company found for selector '${normalizedSelector}'.`);
}
assertDeleteConfirmation(target, opts);
await ctx.api.delete<{ ok: true }>(`/api/companies/${target.id}`);
printOutput(
{
ok: true,
deletedCompanyId: target.id,
deletedCompanyName: target.name,
deletedCompanyPrefix: target.issuePrefix,
},
{ json: ctx.json },
);
} catch (err) {
handleCommandError(err);
}
}),
);
}

7
packages/adapter-utils/src/types.ts
View File

@@ -66,6 +66,7 @@ export interface AdapterInvocationMeta {
command: string;
cwd?: string;
commandArgs?: string[];
commandNotes?: string[];
env?: Record<string, string>;
prompt?: string;
context?: Record<string, unknown>;
@@ -110,6 +111,12 @@ export interface AdapterEnvironmentTestContext {
companyId: string;
adapterType: string;
config: Record<string, unknown>;
deployment?: {
mode?: "local_trusted" | "authenticated";
exposure?: "private" | "public";
bindHost?: string | null;
allowedHostnames?: string[];
};
}
export interface ServerAdapterModule {

1
packages/adapters/claude-local/src/index.ts
View File

@@ -18,7 +18,6 @@ Core fields:
- effort (string, optional): reasoning effort passed via --effort (low|medium|high)
- chrome (boolean, optional): pass --chrome when running Claude
- promptTemplate (string, optional): run prompt template
- bootstrapPromptTemplate (string, optional): first-run prompt template
- maxTurnsPerRun (number, optional): max turns for one run
- dangerouslySkipPermissions (boolean, optional): pass --dangerously-skip-permissions to claude
- command (string, optional): defaults to "claude"

10
packages/adapters/claude-local/src/server/execute.ts
View File

@@ -261,7 +261,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
config.promptTemplate,
"You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
);
const bootstrapTemplate = asString(config.bootstrapPromptTemplate, promptTemplate);
const model = asString(config.model, "");
const effort = asString(config.effort, "");
const chrome = asBoolean(config.chrome, false);
@@ -269,6 +268,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
const dangerouslySkipPermissions = asBoolean(config.dangerouslySkipPermissions, false);
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const instructionsFileDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
const commandNotes = instructionsFilePath
? [
`Injected agent instructions via --append-system-prompt-file ${instructionsFilePath} (with path directive appended)`,
]
: [];
const runtimeConfig = await buildClaudeRuntimeConfig({
runId,
@@ -316,8 +320,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
`[paperclip] Claude session "${runtimeSessionId}" was saved for cwd "${runtimeSessionCwd}" and will not be resumed in "${cwd}".\n`,
);
}
const template = sessionId ? promptTemplate : bootstrapTemplate;
const prompt = renderTemplate(template, {
const prompt = renderTemplate(promptTemplate, {
agentId: agent.id,
companyId: agent.companyId,
runId,
@@ -367,6 +370,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
command,
cwd,
commandArgs: args,
commandNotes,
env: redactEnvForLogs(env),
prompt,
context,

1
packages/adapters/claude-local/src/ui/build-config.ts
View File

@@ -55,7 +55,6 @@ export function buildClaudeLocalConfig(v: CreateConfigValues): Record<string, un
if (v.cwd) ac.cwd = v.cwd;
if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
if (v.model) ac.model = v.model;
if (v.thinkingEffort) ac.effort = v.thinkingEffort;
if (v.chrome) ac.chrome = true;

1
packages/adapters/codex-local/src/index.ts
View File

@@ -23,7 +23,6 @@ Core fields:
- model (string, optional): Codex model id
- modelReasoningEffort (string, optional): reasoning effort override (minimal|low|medium|high) passed via -c model_reasoning_effort=...
- promptTemplate (string, optional): run prompt template
- bootstrapPromptTemplate (string, optional): first-run prompt template
- search (boolean, optional): run codex with --search
- dangerouslyBypassApprovalsAndSandbox (boolean, optional): run with bypass flag
- command (string, optional): defaults to "codex"

19
packages/adapters/codex-local/src/server/execute.ts
View File

@@ -105,7 +105,6 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
config.promptTemplate,
"You are agent {{agent.id}} ({{agent.name}}). Continue your Paperclip work.",
);
const bootstrapTemplate = asString(config.bootstrapPromptTemplate, promptTemplate);
const command = asString(config.command, "codex");
const model = asString(config.model, "");
const modelReasoningEffort = asString(
@@ -231,11 +230,11 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
);
}
const instructionsFilePath = asString(config.instructionsFilePath, "").trim();
const instructionsDir = instructionsFilePath ? `${path.dirname(instructionsFilePath)}/` : "";
let instructionsPrefix = "";
if (instructionsFilePath) {
try {
const instructionsContents = await fs.readFile(instructionsFilePath, "utf8");
const instructionsDir = `${path.dirname(instructionsFilePath)}/`;
instructionsPrefix =
`${instructionsContents}\n\n` +
`The above agent instructions were loaded from ${instructionsFilePath}. ` +
@@ -252,8 +251,19 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
);
}
}
const template = sessionId ? promptTemplate : bootstrapTemplate;
const renderedPrompt = renderTemplate(template, {
const commandNotes = (() => {
if (!instructionsFilePath) return [] as string[];
if (instructionsPrefix.length > 0) {
return [
`Loaded agent instructions from ${instructionsFilePath}`,
`Prepended instructions + path directive to stdin prompt (relative references from ${instructionsDir}).`,
];
}
return [
`Configured instructionsFilePath ${instructionsFilePath}, but file could not be read; continuing without injected instructions.`,
];
})();
const renderedPrompt = renderTemplate(promptTemplate, {
agentId: agent.id,
companyId: agent.companyId,
runId,
@@ -283,6 +293,7 @@ export async function execute(ctx: AdapterExecutionContext): Promise<AdapterExec
adapterType: "codex_local",
command,
cwd,
commandNotes,
commandArgs: args.map((value, idx) => {
if (idx === args.length - 1 && value !== "-") return `<prompt ${prompt.length} chars>`;
return value;

1
packages/adapters/codex-local/src/ui/build-config.ts
View File

@@ -55,7 +55,6 @@ export function buildCodexLocalConfig(v: CreateConfigValues): Record<string, unk
if (v.cwd) ac.cwd = v.cwd;
if (v.instructionsFilePath) ac.instructionsFilePath = v.instructionsFilePath;
if (v.promptTemplate) ac.promptTemplate = v.promptTemplate;
if (v.bootstrapPrompt) ac.bootstrapPromptTemplate = v.bootstrapPrompt;
if (v.model) ac.model = v.model;
if (v.thinkingEffort) ac.modelReasoningEffort = v.thinkingEffort;
ac.timeoutSec = 0;

77
packages/adapters/openclaw/src/server/test.ts
View File

@@ -16,6 +16,81 @@ function isLoopbackHost(hostname: string): boolean {
return value === "localhost" || value === "127.0.0.1" || value === "::1";
}
function normalizeHostname(value: string | null | undefined): string | null {
if (!value) return null;
const trimmed = value.trim();
if (!trimmed) return null;
if (trimmed.startsWith("[")) {
const end = trimmed.indexOf("]");
return end > 1 ? trimmed.slice(1, end).toLowerCase() : trimmed.toLowerCase();
}
const firstColon = trimmed.indexOf(":");
if (firstColon > -1) return trimmed.slice(0, firstColon).toLowerCase();
return trimmed.toLowerCase();
}
function pushDeploymentDiagnostics(
checks: AdapterEnvironmentCheck[],
ctx: AdapterEnvironmentTestContext,
endpointUrl: URL | null,
) {
const mode = ctx.deployment?.mode;
const exposure = ctx.deployment?.exposure;
const bindHost = normalizeHostname(ctx.deployment?.bindHost ?? null);
const allowSet = new Set(
(ctx.deployment?.allowedHostnames ?? [])
.map((entry) => normalizeHostname(entry))
.filter((entry): entry is string => Boolean(entry)),
);
const endpointHost = endpointUrl ? normalizeHostname(endpointUrl.hostname) : null;
if (!mode) return;
checks.push({
code: "openclaw_deployment_context",
level: "info",
message: `Deployment context: mode=${mode}${exposure ? ` exposure=${exposure}` : ""}`,
});
if (mode === "authenticated" && exposure === "private") {
if (bindHost && !isLoopbackHost(bindHost) && !allowSet.has(bindHost)) {
checks.push({
code: "openclaw_private_bind_hostname_not_allowed",
level: "warn",
message: `Paperclip bind host "${bindHost}" is not in allowed hostnames.`,
hint: `Run pnpm paperclip allowed-hostname ${bindHost} so remote OpenClaw callbacks can pass host checks.`,
});
}
if (!bindHost || isLoopbackHost(bindHost)) {
checks.push({
code: "openclaw_private_bind_loopback",
level: "warn",
message: "Paperclip is bound to loopback in authenticated/private mode.",
hint: "Bind to a reachable private hostname/IP so remote OpenClaw agents can call back.",
});
}
if (endpointHost && !isLoopbackHost(endpointHost) && allowSet.size === 0) {
checks.push({
code: "openclaw_private_no_allowed_hostnames",
level: "warn",
message: "No explicit allowed hostnames are configured for authenticated/private mode.",
hint: "Set one with pnpm paperclip allowed-hostname <host> when OpenClaw runs on another machine.",
});
}
}
if (mode === "authenticated" && exposure === "public" && endpointUrl && endpointUrl.protocol !== "https:") {
checks.push({
code: "openclaw_public_http_endpoint",
level: "warn",
message: "OpenClaw endpoint uses HTTP in authenticated/public mode.",
hint: "Prefer HTTPS for public deployments.",
});
}
}
export async function testEnvironment(
ctx: AdapterEnvironmentTestContext,
): Promise<AdapterEnvironmentTestResult> {
@@ -75,6 +150,8 @@ export async function testEnvironment(
}
}
pushDeploymentDiagnostics(checks, ctx, url);
const method = asString(config.method, "POST").trim().toUpperCase() || "POST";
checks.push({
code: "openclaw_method_configured",

3
packages/shared/src/index.ts
View File

@@ -229,7 +229,8 @@ export {
} from "./validators/index.js";
export { API_PREFIX, API } from "./api.js";
export { normalizeAgentUrlKey, deriveAgentUrlKey } from "./agent-url-key.js";
export { normalizeAgentUrlKey, deriveAgentUrlKey, isUuidLike } from "./agent-url-key.js";
export { deriveProjectUrlKey, normalizeProjectUrlKey } from "./project-url-key.js";
export {
PROJECT_MENTION_SCHEME,
buildProjectMentionHref,

1
packages/shared/src/types/agent.ts
View File

@@ -12,6 +12,7 @@ export interface Agent {
id: string;
companyId: string;
name: string;
urlKey: string;
role: AgentRole;
title: string | null;
icon: string | null;

1
packages/shared/src/types/project.ts
View File

@@ -22,6 +22,7 @@ export interface ProjectWorkspace {
export interface Project {
id: string;
companyId: string;
urlKey: string;
/** @deprecated Use goalIds / goals instead */
goalId: string | null;
goalIds: string[];

35
packages/shared/src/validators/index.ts
View File

@@ -4,6 +4,23 @@ export {
type CreateCompany,
type UpdateCompany,
} from "./company.js";
export {
portabilityIncludeSchema,
portabilitySecretRequirementSchema,
portabilityCompanyManifestEntrySchema,
portabilityAgentManifestEntrySchema,
portabilityManifestSchema,
portabilitySourceSchema,
portabilityTargetSchema,
portabilityAgentSelectionSchema,
portabilityCollisionStrategySchema,
companyPortabilityExportSchema,
companyPortabilityPreviewSchema,
companyPortabilityImportSchema,
type CompanyPortabilityExport,
type CompanyPortabilityPreview,
type CompanyPortabilityImport,
} from "./company-portability.js";
export {
createAgentSchema,
@@ -114,21 +131,3 @@ export {
type UpdateMemberPermissions,
type UpdateUserCompanyAccess,
} from "./access.js";
export {
portabilityIncludeSchema,
portabilitySecretRequirementSchema,
portabilityCompanyManifestEntrySchema,
portabilityAgentManifestEntrySchema,
portabilityManifestSchema,
portabilitySourceSchema,
portabilityTargetSchema,
portabilityAgentSelectionSchema,
portabilityCollisionStrategySchema,
companyPortabilityExportSchema,
companyPortabilityPreviewSchema,
companyPortabilityImportSchema,
type CompanyPortabilityExport,
type CompanyPortabilityPreview,
type CompanyPortabilityImport,
} from "./company-portability.js";

1
packages/shared/src/validators/issue.ts
View File

@@ -50,6 +50,7 @@ export type CheckoutIssue = z.infer<typeof checkoutIssueSchema>;
export const addIssueCommentSchema = z.object({
body: z.string().min(1),
reopen: z.boolean().optional(),
interrupt: z.boolean().optional(),
});
export type AddIssueComment = z.infer<typeof addIssueCommentSchema>;

11
server/src/app.ts
View File

@@ -38,6 +38,7 @@ export async function createApp(
allowedHostnames: string[];
bindHost: string;
authReady: boolean;
companyDeletionEnabled: boolean;
betterAuthHandler?: express.RequestHandler;
resolveSession?: (req: ExpressRequest) => Promise<BetterAuthSessionResult | null>;
},
@@ -79,6 +80,7 @@ export async function createApp(
deploymentMode: opts.deploymentMode,
deploymentExposure: opts.deploymentExposure,
authReady: opts.authReady,
companyDeletionEnabled: opts.companyDeletionEnabled,
}),
);
api.use("/companies", companyRoutes(db));
@@ -93,7 +95,14 @@ export async function createApp(
api.use(activityRoutes(db));
api.use(dashboardRoutes(db));
api.use(sidebarBadgeRoutes(db));
api.use(accessRoutes(db));
api.use(
accessRoutes(db, {
deploymentMode: opts.deploymentMode,
deploymentExposure: opts.deploymentExposure,
bindHost: opts.bindHost,
allowedHostnames: opts.allowedHostnames,
}),
);
app.use("/api", api);
const __dirname = path.dirname(fileURLToPath(import.meta.url));

7
server/src/config.ts
View File

@@ -54,6 +54,7 @@ export interface Config {
storageS3ForcePathStyle: boolean;
heartbeatSchedulerEnabled: boolean;
heartbeatSchedulerIntervalMs: number;
companyDeletionEnabled: boolean;
}
export function loadConfig(): Config {
@@ -142,6 +143,11 @@ export function loadConfig(): Config {
const allowedHostnames = Array.from(
new Set((allowedHostnamesFromEnv ?? fileConfig?.server.allowedHostnames ?? []).map((value) => value.trim().toLowerCase()).filter(Boolean)),
);
const companyDeletionEnvRaw = process.env.PAPERCLIP_ENABLE_COMPANY_DELETION;
const companyDeletionEnabled =
companyDeletionEnvRaw !== undefined
? companyDeletionEnvRaw === "true"
: deploymentMode === "local_trusted";
return {
deploymentMode,
@@ -179,5 +185,6 @@ export function loadConfig(): Config {
storageS3ForcePathStyle,
heartbeatSchedulerEnabled: process.env.HEARTBEAT_SCHEDULER_ENABLED !== "false",
heartbeatSchedulerIntervalMs: Math.max(10000, Number(process.env.HEARTBEAT_SCHEDULER_INTERVAL_MS) || 30000),
companyDeletionEnabled,
};
}

1
server/src/index.ts
View File

@@ -357,6 +357,7 @@ const app = await createApp(db as any, {
allowedHostnames: config.allowedHostnames,
bindHost: config.host,
authReady,
companyDeletionEnabled: config.companyDeletionEnabled,
betterAuthHandler,
resolveSession,
});

268
server/src/routes/access.ts
View File

@@ -21,6 +21,7 @@ import {
updateUserCompanyAccessSchema,
PERMISSION_KEYS,
} from "@paperclip/shared";
import type { DeploymentExposure, DeploymentMode } from "@paperclip/shared";
import { forbidden, conflict, notFound, unauthorized, badRequest } from "../errors.js";
import { validate } from "../middleware/validate.js";
import { accessService, agentService, logActivity } from "../services/index.js";
@@ -76,6 +77,218 @@ function toJoinRequestResponse(row: typeof joinRequests.$inferSelect) {
return safe;
}
type JoinDiagnostic = {
code: string;
level: "info" | "warn";
message: string;
hint?: string;
};
function isPlainObject(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function isLoopbackHost(hostname: string): boolean {
const value = hostname.trim().toLowerCase();
return value === "localhost" || value === "127.0.0.1" || value === "::1";
}
function normalizeHostname(value: string | null | undefined): string | null {
if (!value) return null;
const trimmed = value.trim();
if (!trimmed) return null;
if (trimmed.startsWith("[")) {
const end = trimmed.indexOf("]");
return end > 1 ? trimmed.slice(1, end).toLowerCase() : trimmed.toLowerCase();
}
const firstColon = trimmed.indexOf(":");
if (firstColon > -1) return trimmed.slice(0, firstColon).toLowerCase();
return trimmed.toLowerCase();
}
function normalizeHeaderMap(input: unknown): Record<string, string> | undefined {
if (!isPlainObject(input)) return undefined;
const out: Record<string, string> = {};
for (const [key, value] of Object.entries(input)) {
if (typeof value !== "string") continue;
const trimmedKey = key.trim();
const trimmedValue = value.trim();
if (!trimmedKey || !trimmedValue) continue;
out[trimmedKey] = trimmedValue;
}
return Object.keys(out).length > 0 ? out : undefined;
}
function buildJoinConnectivityDiagnostics(input: {
deploymentMode: DeploymentMode;
deploymentExposure: DeploymentExposure;
bindHost: string;
allowedHostnames: string[];
callbackUrl: URL | null;
}): JoinDiagnostic[] {
const diagnostics: JoinDiagnostic[] = [];
const bindHost = normalizeHostname(input.bindHost);
const callbackHost = input.callbackUrl ? normalizeHostname(input.callbackUrl.hostname) : null;
const allowSet = new Set(
input.allowedHostnames
.map((entry) => normalizeHostname(entry))
.filter((entry): entry is string => Boolean(entry)),
);
diagnostics.push({
code: "openclaw_deployment_context",
level: "info",
message: `Deployment context: mode=${input.deploymentMode}, exposure=${input.deploymentExposure}.`,
});
if (input.deploymentMode === "authenticated" && input.deploymentExposure === "private") {
if (!bindHost || isLoopbackHost(bindHost)) {
diagnostics.push({
code: "openclaw_private_bind_loopback",
level: "warn",
message: "Paperclip is bound to loopback in authenticated/private mode.",
hint: "Bind to a reachable private hostname/IP for remote OpenClaw callbacks.",
});
}
if (bindHost && !isLoopbackHost(bindHost) && !allowSet.has(bindHost)) {
diagnostics.push({
code: "openclaw_private_bind_not_allowed",
level: "warn",
message: `Paperclip bind host \"${bindHost}\" is not in allowed hostnames.`,
hint: `Run pnpm paperclip allowed-hostname ${bindHost}`,
});
}
if (callbackHost && !isLoopbackHost(callbackHost) && allowSet.size === 0) {
diagnostics.push({
code: "openclaw_private_allowed_hostnames_empty",
level: "warn",
message: "No explicit allowed hostnames are configured for authenticated/private mode.",
hint: "Set one with pnpm paperclip allowed-hostname <host> when OpenClaw runs off-host.",
});
}
}
if (
input.deploymentMode === "authenticated" &&
input.deploymentExposure === "public" &&
input.callbackUrl &&
input.callbackUrl.protocol !== "https:"
) {
diagnostics.push({
code: "openclaw_public_http_callback",
level: "warn",
message: "OpenClaw callback URL uses HTTP in authenticated/public mode.",
hint: "Prefer HTTPS for public deployments.",
});
}
return diagnostics;
}
function normalizeAgentDefaultsForJoin(input: {
adapterType: string | null;
defaultsPayload: unknown;
deploymentMode: DeploymentMode;
deploymentExposure: DeploymentExposure;
bindHost: string;
allowedHostnames: string[];
}) {
const diagnostics: JoinDiagnostic[] = [];
if (input.adapterType !== "openclaw") {
const normalized = isPlainObject(input.defaultsPayload)
? (input.defaultsPayload as Record<string, unknown>)
: null;
return { normalized, diagnostics };
}
if (!isPlainObject(input.defaultsPayload)) {
diagnostics.push({
code: "openclaw_callback_config_missing",
level: "warn",
message: "No OpenClaw callback config was provided in agentDefaultsPayload.",
hint: "Include agentDefaultsPayload.url so Paperclip can invoke the OpenClaw webhook immediately after approval.",
});
return { normalized: null as Record<string, unknown> | null, diagnostics };
}
const defaults = input.defaultsPayload as Record<string, unknown>;
const normalized: Record<string, unknown> = {};
let callbackUrl: URL | null = null;
const rawUrl = typeof defaults.url === "string" ? defaults.url.trim() : "";
if (!rawUrl) {
diagnostics.push({
code: "openclaw_callback_url_missing",
level: "warn",
message: "OpenClaw callback URL is missing.",
hint: "Set agentDefaultsPayload.url to your OpenClaw webhook endpoint.",
});
} else {
try {
callbackUrl = new URL(rawUrl);
if (callbackUrl.protocol !== "http:" && callbackUrl.protocol !== "https:") {
diagnostics.push({
code: "openclaw_callback_url_protocol",
level: "warn",
message: `Unsupported callback protocol: ${callbackUrl.protocol}`,
hint: "Use http:// or https://.",
});
} else {
normalized.url = callbackUrl.toString();
diagnostics.push({
code: "openclaw_callback_url_configured",
level: "info",
message: `Callback endpoint set to ${callbackUrl.toString()}`,
});
}
if (isLoopbackHost(callbackUrl.hostname)) {
diagnostics.push({
code: "openclaw_callback_loopback",
level: "warn",
message: "OpenClaw callback endpoint uses loopback hostname.",
hint: "Use a reachable hostname/IP when OpenClaw runs on another machine.",
});
}
} catch {
diagnostics.push({
code: "openclaw_callback_url_invalid",
level: "warn",
message: `Invalid callback URL: ${rawUrl}`,
});
}
}
const rawMethod = typeof defaults.method === "string" ? defaults.method.trim().toUpperCase() : "";
normalized.method = rawMethod || "POST";
if (typeof defaults.timeoutSec === "number" && Number.isFinite(defaults.timeoutSec)) {
normalized.timeoutSec = Math.max(1, Math.min(120, Math.floor(defaults.timeoutSec)));
}
const headers = normalizeHeaderMap(defaults.headers);
if (headers) normalized.headers = headers;
if (typeof defaults.webhookAuthHeader === "string" && defaults.webhookAuthHeader.trim()) {
normalized.webhookAuthHeader = defaults.webhookAuthHeader.trim();
}
if (isPlainObject(defaults.payloadTemplate)) {
normalized.payloadTemplate = defaults.payloadTemplate;
}
diagnostics.push(
...buildJoinConnectivityDiagnostics({
deploymentMode: input.deploymentMode,
deploymentExposure: input.deploymentExposure,
bindHost: input.bindHost,
allowedHostnames: input.allowedHostnames,
callbackUrl,
}),
);
return { normalized, diagnostics };
}
function toInviteSummaryResponse(req: Request, token: string, invite: typeof invites.$inferSelect) {
const baseUrl = requestBaseUrl(req);
const onboardingPath = `/api/invites/${token}/onboarding`;
@@ -92,7 +305,17 @@ function toInviteSummaryResponse(req: Request, token: string, invite: typeof inv
};
}
function buildInviteOnboardingManifest(req: Request, token: string, invite: typeof invites.$inferSelect) {
function buildInviteOnboardingManifest(
req: Request,
token: string,
invite: typeof invites.$inferSelect,
opts: {
deploymentMode: DeploymentMode;
deploymentExposure: DeploymentExposure;
bindHost: string;
allowedHostnames: string[];
},
) {
const baseUrl = requestBaseUrl(req);
const skillPath = "/api/skills/paperclip";
const skillUrl = baseUrl ? `${baseUrl}${skillPath}` : skillPath;
@@ -125,6 +348,16 @@ function buildInviteOnboardingManifest(req: Request, token: string, invite: type
claimSecret: "one-time claim secret returned when the join request is created",
},
},
connectivity: {
deploymentMode: opts.deploymentMode,
deploymentExposure: opts.deploymentExposure,
bindHost: opts.bindHost,
allowedHostnames: opts.allowedHostnames,
guidance:
opts.deploymentMode === "authenticated" && opts.deploymentExposure === "private"
? "If OpenClaw runs on another machine, ensure the Paperclip hostname is reachable and allowed via `pnpm paperclip allowed-hostname <host>`."
: "Ensure OpenClaw can reach this Paperclip API base URL for callbacks and claims.",
},
skill: {
name: "paperclip",
path: skillPath,
@@ -194,7 +427,15 @@ function grantsFromDefaults(
return result;
}
export function accessRoutes(db: Db) {
export function accessRoutes(
db: Db,
opts: {
deploymentMode: DeploymentMode;
deploymentExposure: DeploymentExposure;
bindHost: string;
allowedHostnames: string[];
},
) {
const router = Router();
const access = accessService(db);
const agents = agentService(db);
@@ -341,7 +582,7 @@ export function accessRoutes(db: Db) {
throw notFound("Invite not found");
}
res.json(buildInviteOnboardingManifest(req, token, invite));
res.json(buildInviteOnboardingManifest(req, token, invite, opts));
});
router.post("/invites/:token/accept", validate(acceptInviteSchema), async (req, res) => {
@@ -401,6 +642,17 @@ export function accessRoutes(db: Db) {
throw badRequest("agentName is required for agent join requests");
}
const joinDefaults = requestType === "agent"
? normalizeAgentDefaultsForJoin({
adapterType: req.body.adapterType ?? null,
defaultsPayload: req.body.agentDefaultsPayload ?? null,
deploymentMode: opts.deploymentMode,
deploymentExposure: opts.deploymentExposure,
bindHost: opts.bindHost,
allowedHostnames: opts.allowedHostnames,
})
: { normalized: null as Record<string, unknown> | null, diagnostics: [] as JoinDiagnostic[] };
const claimSecret = requestType === "agent" ? createClaimSecret() : null;
const claimSecretHash = claimSecret ? hashToken(claimSecret) : null;
const claimSecretExpiresAt = claimSecret
@@ -427,7 +679,7 @@ export function accessRoutes(db: Db) {
agentName: requestType === "agent" ? req.body.agentName : null,
adapterType: requestType === "agent" ? req.body.adapterType ?? null : null,
capabilities: requestType === "agent" ? req.body.capabilities ?? null : null,
agentDefaultsPayload: requestType === "agent" ? req.body.agentDefaultsPayload ?? null : null,
agentDefaultsPayload: requestType === "agent" ? joinDefaults.normalized : null,
claimSecretHash,
claimSecretExpiresAt,
})
@@ -451,16 +703,20 @@ export function accessRoutes(db: Db) {
const response = toJoinRequestResponse(created);
if (claimSecret) {
const onboardingManifest = buildInviteOnboardingManifest(req, token, invite);
const onboardingManifest = buildInviteOnboardingManifest(req, token, invite, opts);
res.status(202).json({
...response,
claimSecret,
claimApiKeyPath: `/api/join-requests/${created.id}/claim-api-key`,
onboarding: onboardingManifest.onboarding,
diagnostics: joinDefaults.diagnostics,
});
return;
}
res.status(202).json(response);
res.status(202).json({
...response,
...(joinDefaults.diagnostics.length > 0 ? { diagnostics: joinDefaults.diagnostics } : {}),
});
});
router.post("/invites/:inviteId/revoke", async (req, res) => {

5
server/src/routes/health.ts
View File

@@ -10,10 +10,12 @@ export function healthRoutes(
deploymentMode: DeploymentMode;
deploymentExposure: DeploymentExposure;
authReady: boolean;
companyDeletionEnabled: boolean;
} = {
deploymentMode: "local_trusted",
deploymentExposure: "private",
authReady: true,
companyDeletionEnabled: true,
},
) {
const router = Router();
@@ -40,6 +42,9 @@ export function healthRoutes(
deploymentExposure: opts.deploymentExposure,
authReady: opts.authReady,
bootstrapStatus,
features: {
companyDeletionEnabled: opts.companyDeletionEnabled,
},
});
});

54
server/src/routes/issues.ts
View File

@@ -710,9 +710,11 @@ export function issueRoutes(db: Db, storage: StorageService) {
const actor = getActorInfo(req);
const reopenRequested = req.body.reopen === true;
const interruptRequested = req.body.interrupt === true;
const isClosed = issue.status === "done" || issue.status === "cancelled";
let reopened = false;
let reopenFromStatus: string | null = null;
let interruptedRunId: string | null = null;
let currentIssue = issue;
if (reopenRequested && isClosed) {
@@ -744,6 +746,52 @@ export function issueRoutes(db: Db, storage: StorageService) {
});
}
if (interruptRequested) {
if (req.actor.type !== "board") {
res.status(403).json({ error: "Only board users can interrupt active runs from issue comments" });
return;
}
let runToInterrupt = currentIssue.executionRunId
? await heartbeat.getRun(currentIssue.executionRunId)
: null;
if (
(!runToInterrupt || runToInterrupt.status !== "running") &&
currentIssue.assigneeAgentId
) {
const activeRun = await heartbeat.getActiveRunForAgent(currentIssue.assigneeAgentId);
const activeIssueId =
activeRun &&
activeRun.contextSnapshot &&
typeof activeRun.contextSnapshot === "object" &&
typeof (activeRun.contextSnapshot as Record<string, unknown>).issueId === "string"
? ((activeRun.contextSnapshot as Record<string, unknown>).issueId as string)
: null;
if (activeRun && activeRun.status === "running" && activeIssueId === currentIssue.id) {
runToInterrupt = activeRun;
}
}
if (runToInterrupt && runToInterrupt.status === "running") {
const cancelled = await heartbeat.cancelRun(runToInterrupt.id);
if (cancelled) {
interruptedRunId = cancelled.id;
await logActivity(db, {
companyId: cancelled.companyId,
actorType: actor.actorType,
actorId: actor.actorId,
agentId: actor.agentId,
runId: actor.runId,
action: "heartbeat.cancelled",
entityType: "heartbeat_run",
entityId: cancelled.id,
details: { agentId: cancelled.agentId, source: "issue_comment_interrupt", issueId: currentIssue.id },
});
}
}
}
const comment = await svc.addComment(id, req.body.body, {
agentId: actor.agentId ?? undefined,
userId: actor.actorType === "user" ? actor.actorId : undefined,
@@ -763,6 +811,8 @@ export function issueRoutes(db: Db, storage: StorageService) {
bodySnippet: comment.body.slice(0, 120),
identifier: currentIssue.identifier,
issueTitle: currentIssue.title,
...(reopened ? { reopened: true, reopenedFrom: reopenFromStatus, source: "comment" } : {}),
...(interruptedRunId ? { interruptedRunId } : {}),
},
});
@@ -781,6 +831,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
commentId: comment.id,
reopenedFrom: reopenFromStatus,
mutation: "comment",
...(interruptedRunId ? { interruptedRunId } : {}),
},
requestedByActorType: actor.actorType,
requestedByActorId: actor.actorId,
@@ -791,6 +842,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
source: "issue.comment.reopen",
wakeReason: "issue_reopened_via_comment",
reopenedFrom: reopenFromStatus,
...(interruptedRunId ? { interruptedRunId } : {}),
},
});
} else {
@@ -802,6 +854,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
issueId: currentIssue.id,
commentId: comment.id,
mutation: "comment",
...(interruptedRunId ? { interruptedRunId } : {}),
},
requestedByActorType: actor.actorType,
requestedByActorId: actor.actorId,
@@ -811,6 +864,7 @@ export function issueRoutes(db: Db, storage: StorageService) {
commentId: comment.id,
source: "issue.comment",
wakeReason: "issue_commented",
...(interruptedRunId ? { interruptedRunId } : {}),
},
});
}

40
server/src/routes/projects.ts
View File

@@ -1,19 +1,57 @@
import { Router } from "express";
import { Router, type Request } from "express";
import type { Db } from "@paperclip/db";
import {
createProjectSchema,
createProjectWorkspaceSchema,
isUuidLike,
updateProjectSchema,
updateProjectWorkspaceSchema,
} from "@paperclip/shared";
import { validate } from "../middleware/validate.js";
import { projectService, logActivity } from "../services/index.js";
import { conflict } from "../errors.js";
import { assertCompanyAccess, getActorInfo } from "./authz.js";
export function projectRoutes(db: Db) {
const router = Router();
const svc = projectService(db);
async function resolveCompanyIdForProjectReference(req: Request) {
const companyIdQuery = req.query.companyId;
const requestedCompanyId =
typeof companyIdQuery === "string" && companyIdQuery.trim().length > 0
? companyIdQuery.trim()
: null;
if (requestedCompanyId) {
assertCompanyAccess(req, requestedCompanyId);
return requestedCompanyId;
}
if (req.actor.type === "agent" && req.actor.companyId) {
return req.actor.companyId;
}
return null;
}
async function normalizeProjectReference(req: Request, rawId: string) {
if (isUuidLike(rawId)) return rawId;
const companyId = await resolveCompanyIdForProjectReference(req);
if (!companyId) return rawId;
const resolved = await svc.resolveByReference(companyId, rawId);
if (resolved.ambiguous) {
throw conflict("Project shortname is ambiguous in this company. Use the project ID.");
}
return resolved.project?.id ?? rawId;
}
router.param("id", async (req, _res, next, rawId) => {
try {
req.params.id = await normalizeProjectReference(req, rawId);
next();
} catch (err) {
next(err);
}
});
router.get("/companies/:companyId/projects", async (req, res) => {
const companyId = req.params.companyId as string;
assertCompanyAccess(req, companyId);

44
server/src/services/agents.ts
View File

@@ -11,6 +11,7 @@ import {
heartbeatRunEvents,
heartbeatRuns,
} from "@paperclip/db";
import { isUuidLike, normalizeAgentUrlKey } from "@paperclip/shared";
import { conflict, notFound, unprocessable } from "../errors.js";
import { normalizeAgentPermissions } from "./agent-permissions.js";
import { REDACTED_EVENT_VALUE, sanitizeRecord } from "../redaction.js";
@@ -140,13 +141,20 @@ function configPatchFromSnapshot(snapshot: unknown): Partial<typeof agents.$infe
}
export function agentService(db: Db) {
function normalizeAgentRow(row: typeof agents.$inferSelect) {
function withUrlKey<T extends { id: string; name: string }>(row: T) {
return {
...row,
permissions: normalizeAgentPermissions(row.permissions, row.role),
urlKey: normalizeAgentUrlKey(row.name) ?? row.id,
};
}
function normalizeAgentRow(row: typeof agents.$inferSelect) {
return withUrlKey({
...row,
permissions: normalizeAgentPermissions(row.permissions, row.role),
});
}
async function getById(id: string) {
const row = await db
.select()
@@ -502,5 +510,37 @@ export function agentService(db: Db) {
.select()
.from(heartbeatRuns)
.where(and(eq(heartbeatRuns.agentId, agentId), inArray(heartbeatRuns.status, ["queued", "running"]))),
resolveByReference: async (companyId: string, reference: string) => {
const raw = reference.trim();
if (raw.length === 0) {
return { agent: null, ambiguous: false } as const;
}
if (isUuidLike(raw)) {
const byId = await getById(raw);
if (!byId || byId.companyId !== companyId) {
return { agent: null, ambiguous: false } as const;
}
return { agent: byId, ambiguous: false } as const;
}
const urlKey = normalizeAgentUrlKey(raw);
if (!urlKey) {
return { agent: null, ambiguous: false } as const;
}
const rows = await db.select().from(agents).where(eq(agents.companyId, companyId));
const matches = rows
.map(normalizeAgentRow)
.filter((agent) => agent.urlKey === urlKey && agent.status !== "terminated");
if (matches.length === 1) {
return { agent: matches[0] ?? null, ambiguous: false } as const;
}
if (matches.length > 1) {
return { agent: null, ambiguous: true } as const;
}
return { agent: null, ambiguous: false } as const;
},
};
}

49
server/src/services/heartbeat.ts
View File

@@ -1606,8 +1606,14 @@ export function heartbeatService(db: Db) {
const executionAgentNameKey =
normalizeAgentNameKey(issue.executionAgentNameKey) ??
normalizeAgentNameKey(executionAgent?.name);
const isSameExecutionAgent =
Boolean(executionAgentNameKey) && executionAgentNameKey === agentNameKey;
const shouldQueueFollowupForCommentWake =
Boolean(wakeCommentId) &&
activeExecutionRun.status === "running" &&
isSameExecutionAgent;
if (executionAgentNameKey && executionAgentNameKey === agentNameKey) {
if (isSameExecutionAgent && !shouldQueueFollowupForCommentWake) {
const mergedContextSnapshot = mergeCoalescedContextSnapshot(
activeExecutionRun.contextSnapshot,
enrichedContextSnapshot,
@@ -1647,6 +1653,47 @@ export function heartbeatService(db: Db) {
[DEFERRED_WAKE_CONTEXT_KEY]: enrichedContextSnapshot,
};
const existingDeferred = await tx
.select()
.from(agentWakeupRequests)
.where(
and(
eq(agentWakeupRequests.companyId, agent.companyId),
eq(agentWakeupRequests.agentId, agentId),
eq(agentWakeupRequests.status, "deferred_issue_execution"),
sql`${agentWakeupRequests.payload} ->> 'issueId' = ${issue.id}`,
),
)
.orderBy(asc(agentWakeupRequests.requestedAt))
.limit(1)
.then((rows) => rows[0] ?? null);
if (existingDeferred) {
const existingDeferredPayload = parseObject(existingDeferred.payload);
const existingDeferredContext = parseObject(existingDeferredPayload[DEFERRED_WAKE_CONTEXT_KEY]);
const mergedDeferredContext = mergeCoalescedContextSnapshot(
existingDeferredContext,
enrichedContextSnapshot,
);
const mergedDeferredPayload = {
...existingDeferredPayload,
...(payload ?? {}),
issueId,
[DEFERRED_WAKE_CONTEXT_KEY]: mergedDeferredContext,
};
await tx
.update(agentWakeupRequests)
.set({
payload: mergedDeferredPayload,
coalescedCount: (existingDeferred.coalescedCount ?? 0) + 1,
updatedAt: new Date(),
})
.where(eq(agentWakeupRequests.id, existingDeferred.id));
return { kind: "deferred" as const };
}
await tx.insert(agentWakeupRequests).values({
companyId: agent.companyId,
agentId,

62
server/src/services/issues.ts
View File

@@ -56,7 +56,18 @@ export interface IssueFilters {
type IssueRow = typeof issues.$inferSelect;
type IssueLabelRow = typeof labels.$inferSelect;
type IssueActiveRunRow = {
id: string;
status: string;
agentId: string;
invocationSource: string;
triggerDetail: string | null;
startedAt: Date | null;
finishedAt: Date | null;
createdAt: Date;
};
type IssueWithLabels = IssueRow & { labels: IssueLabelRow[]; labelIds: string[] };
type IssueWithLabelsAndRun = IssueWithLabels & { activeRun: IssueActiveRunRow | null };
function sameRunLock(checkoutRunId: string | null, actorRunId: string | null) {
if (actorRunId) return checkoutRunId === actorRunId;
@@ -103,6 +114,53 @@ async function withIssueLabels(dbOrTx: any, rows: IssueRow[]): Promise<IssueWith
});
}
const ACTIVE_RUN_STATUSES = ["queued", "running"];
async function activeRunMapForIssues(
dbOrTx: any,
issueRows: IssueWithLabels[],
): Promise<Map<string, IssueActiveRunRow>> {
const map = new Map<string, IssueActiveRunRow>();
const runIds = issueRows
.map((row) => row.executionRunId)
.filter((id): id is string => id != null);
if (runIds.length === 0) return map;
const rows = await dbOrTx
.select({
id: heartbeatRuns.id,
status: heartbeatRuns.status,
agentId: heartbeatRuns.agentId,
invocationSource: heartbeatRuns.invocationSource,
triggerDetail: heartbeatRuns.triggerDetail,
startedAt: heartbeatRuns.startedAt,
finishedAt: heartbeatRuns.finishedAt,
createdAt: heartbeatRuns.createdAt,
})
.from(heartbeatRuns)
.where(
and(
inArray(heartbeatRuns.id, runIds),
inArray(heartbeatRuns.status, ACTIVE_RUN_STATUSES),
),
);
for (const row of rows) {
map.set(row.id, row);
}
return map;
}
function withActiveRuns(
issueRows: IssueWithLabels[],
runMap: Map<string, IssueActiveRunRow>,
): IssueWithLabelsAndRun[] {
return issueRows.map((row) => ({
...row,
activeRun: row.executionRunId ? (runMap.get(row.executionRunId) ?? null) : null,
}));
}
export function issueService(db: Db) {
async function assertAssignableAgent(companyId: string, agentId: string) {
const assignee = await db
@@ -293,7 +351,9 @@ export function issueService(db: Db) {
.from(issues)
.where(and(...conditions))
.orderBy(hasSearch ? asc(searchOrder) : asc(priorityOrder), asc(priorityOrder), desc(issues.updatedAt));
return withIssueLabels(db, rows);
const withLabels = await withIssueLabels(db, rows);
const runMap = await activeRunMapForIssues(db, withLabels);
return withActiveRuns(withLabels, runMap);
},
getById: async (id: string) => {

65
server/src/services/projects.ts
View File

@@ -1,7 +1,14 @@
import { and, asc, desc, eq, inArray } from "drizzle-orm";
import type { Db } from "@paperclip/db";
import { projects, projectGoals, goals, projectWorkspaces } from "@paperclip/db";
import { PROJECT_COLORS, type ProjectGoalRef, type ProjectWorkspace } from "@paperclip/shared";
import {
PROJECT_COLORS,
deriveProjectUrlKey,
isUuidLike,
normalizeProjectUrlKey,
type ProjectGoalRef,
type ProjectWorkspace,
} from "@paperclip/shared";
type ProjectRow = typeof projects.$inferSelect;
type ProjectWorkspaceRow = typeof projectWorkspaces.$inferSelect;
@@ -17,6 +24,7 @@ type CreateWorkspaceInput = {
type UpdateWorkspaceInput = Partial<CreateWorkspaceInput>;
interface ProjectWithGoals extends ProjectRow {
urlKey: string;
goalIds: string[];
goals: ProjectGoalRef[];
workspaces: ProjectWorkspace[];
@@ -52,7 +60,12 @@ async function attachGoals(db: Db, rows: ProjectRow[]): Promise<ProjectWithGoals
return rows.map((r) => {
const g = map.get(r.id) ?? [];
return { ...r, goalIds: g.map((x) => x.id), goals: g } as ProjectWithGoals;
return {
...r,
urlKey: deriveProjectUrlKey(r.name, r.id),
goalIds: g.map((x) => x.id),
goals: g,
} as ProjectWithGoals;
});
}
@@ -314,7 +327,11 @@ export function projectService(db: Db) {
.delete(projects)
.where(eq(projects.id, id))
.returning()
.then((rows) => rows[0] ?? null),
.then((rows) => {
const row = rows[0] ?? null;
if (!row) return null;
return { ...row, urlKey: deriveProjectUrlKey(row.name, row.id) };
}),
listWorkspaces: async (projectId: string): Promise<ProjectWorkspace[]> => {
const rows = await db
@@ -555,5 +572,47 @@ export function projectService(db: Db) {
return removed ? toWorkspace(removed) : null;
},
resolveByReference: async (companyId: string, reference: string) => {
const raw = reference.trim();
if (raw.length === 0) {
return { project: null, ambiguous: false } as const;
}
if (isUuidLike(raw)) {
const row = await db
.select({ id: projects.id, companyId: projects.companyId, name: projects.name })
.from(projects)
.where(and(eq(projects.id, raw), eq(projects.companyId, companyId)))
.then((rows) => rows[0] ?? null);
if (!row) return { project: null, ambiguous: false } as const;
return {
project: { id: row.id, companyId: row.companyId, urlKey: deriveProjectUrlKey(row.name, row.id) },
ambiguous: false,
} as const;
}
const urlKey = normalizeProjectUrlKey(raw);
if (!urlKey) {
return { project: null, ambiguous: false } as const;
}
const rows = await db
.select({ id: projects.id, companyId: projects.companyId, name: projects.name })
.from(projects)
.where(eq(projects.companyId, companyId));
const matches = rows.filter((row) => deriveProjectUrlKey(row.name, row.id) === urlKey);
if (matches.length === 1) {
const match = matches[0]!;
return {
project: { id: match.id, companyId: match.companyId, urlKey: deriveProjectUrlKey(match.name, match.id) },
ambiguous: false,
} as const;
}
if (matches.length > 1) {
return { project: null, ambiguous: true } as const;
}
return { project: null, ambiguous: false } as const;
},
};
}