[codex] Add routine env secrets support (#6212)

## Thinking Path

> - Paperclip orchestrates AI agents for zero-human companies.
> - Scheduled routines are the control-plane path for recurring agent
work.
> - Routines already had dispatch/history, but their runtime environment
did not carry routine-owned secret bindings through execution.
> - Operators need routine-specific secrets that can override
project/agent env without exposing secret values in history, logs, or
access events.
> - This pull request adds the routine env runtime contract, wires it
into execution, and makes the routine UI/history surfaces show safe
secret metadata.
> - The benefit is that routine executions can use scoped secret refs
predictably while preserving company boundaries and auditability.

## What Changed

- Added routine env persistence/runtime support, including
`routines.env`, `routine_runs.routine_revision_id`, revision snapshots,
and idempotent migration `0086_routine_env_runtime_contract`.
- Resolved routine env during heartbeat adapter config assembly with
precedence `agent < project < routine` and secret access events recorded
against the routine consumer.
- Added secret binding synchronization for routine create/update/restore
flows and guarded cross-company, missing, disabled, and deleted secret
cases.
- Added a Secrets tab to routine detail, env/secret history diff
rendering, and Storybook coverage for the new UI states.
- Added server/UI regression tests, including an embedded-Postgres QA
path for routine secret execution and restore behavior.
- Updated implementation/database docs for routine env and
secret-binding behavior.

## Verification

- `pnpm install --frozen-lockfile` after rebasing onto
`public-gh/master` to refresh workspace links for the newly-added
upstream Grok adapter package.
- `pnpm exec vitest run
server/src/__tests__/heartbeat-project-env.test.ts
server/src/__tests__/routines-service.test.ts
server/src/__tests__/secrets-service.test.ts
server/src/__tests__/qa-routine-secrets-e2e.test.ts
ui/src/components/RoutineHistoryTab.test.tsx` passed: 5 files, 92 tests.
- `pnpm -r typecheck` passed across the workspace.
- `pnpm build` passed. Vite emitted the existing
large-chunk/dynamic-import warnings.
- UI screenshots were captured locally during QA in
`artifacts/pap-9521/` and `artifacts/pap-9522/`; generated screenshots
are not committed to avoid adding binary artifacts to the repo.

## Risks

- Migration risk is limited by `IF NOT EXISTS` guards for the new
columns, FK, and index, and the migration is ordered as `0086`
immediately after upstream `0085`.
- Runtime behavior changes env precedence for routine executions by
adding routine env as the highest-precedence layer; tests cover
agent/project/routine precedence.
- Secret handling is security-sensitive; tests cover value-free
manifests/events/errors, disabled/missing/deleted secrets, and
cross-company rejection.
- UI history now renders routine env/secret diffs; tests and Storybook
stories cover the main rendering paths.

> 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 Codex coding agent based on GPT-5, with shell/tool use and
medium reasoning effort.

## 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
- [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

---------

Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta 2026-05-17 16:30:34 -05:00 committed by GitHub
parent 3e6610fb93
commit 705c1b8d81
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
20 changed files with 1736 additions and 50 deletions

View file

@ -5,7 +5,9 @@ import type { ComponentProps } from "react";
import { createRoot } from "react-dom/client";
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import type {
CompanySecret,
Routine,
RoutineEnvConfig,
RoutineRevision,
RoutineRevisionSnapshotV1,
} from "@paperclipai/shared";
@ -95,6 +97,7 @@ function snapshotV1(overrides?: Partial<RoutineRevisionSnapshotV1["routine"]>):
concurrencyPolicy: "coalesce_if_active",
catchUpPolicy: "skip_missed",
variables: [],
env: null,
...overrides,
},
triggers: [],
@ -321,6 +324,152 @@ describe("RoutineHistoryTab", () => {
expect(successCall).toBeTruthy();
});
it("shows env summary on the revision preview and routes counts into restore dialog", async () => {
const env: RoutineEnvConfig = {
GH_TOKEN: { type: "secret_ref", secretId: "secret-1", version: "latest" },
LOG_LEVEL: { type: "plain", value: "debug" },
};
const current = createRevision({
id: "revision-2",
revisionNumber: 2,
snapshot: snapshotV1({ env }),
});
const old = createRevision({
id: "revision-1",
revisionNumber: 1,
snapshot: snapshotV1({
env: { GH_TOKEN: { type: "secret_ref", secretId: "secret-1", version: 3 } },
}),
});
mockRoutinesApi.listRevisions.mockResolvedValue([current, old]);
const secrets: CompanySecret[] = [
{
id: "secret-1",
companyId: "company-1",
key: "gh_token",
name: "github-bot",
provider: "local_encrypted",
status: "active",
managedMode: "paperclip_managed",
externalRef: null,
providerConfigId: null,
providerMetadata: null,
latestVersion: 4,
description: null,
lastResolvedAt: null,
lastRotatedAt: null,
deletedAt: null,
createdByAgentId: null,
createdByUserId: null,
createdAt: new Date("2026-04-01T00:00:00.000Z"),
updatedAt: new Date("2026-04-01T00:00:00.000Z"),
},
];
await render({ secrets });
expect(container.textContent).toContain("Env");
expect(container.textContent).toContain("2 keys (1 secret ref)");
const oldRow = container.querySelector(
"[data-testid='revision-row-1']",
) as HTMLButtonElement | null;
await act(async () => {
oldRow?.click();
});
await flush();
const restoreButtons = Array.from(container.querySelectorAll("button")).filter(
(button) => button.textContent === "Restore as new revision",
);
expect(restoreButtons.length).toBeGreaterThan(0);
await act(async () => {
restoreButtons[0].click();
});
await flush();
expect(container.textContent).toContain("Routine secrets will revert");
expect(container.textContent).toContain("1 key removed");
expect(container.textContent).toContain("1 key changed");
});
it("labels secret-ref env diffs by changed secret instead of binding kind", async () => {
const current = createRevision({
id: "revision-2",
revisionNumber: 2,
snapshot: snapshotV1({
env: { GH_TOKEN: { type: "secret_ref", secretId: "secret-2", version: "latest" } },
}),
});
const old = createRevision({
id: "revision-1",
revisionNumber: 1,
snapshot: snapshotV1({
env: { GH_TOKEN: { type: "secret_ref", secretId: "secret-1", version: "latest" } },
}),
});
const secrets: CompanySecret[] = [
{
id: "secret-1",
companyId: "company-1",
key: "old_token",
name: "old-token",
provider: "local_encrypted",
status: "active",
managedMode: "paperclip_managed",
externalRef: null,
providerConfigId: null,
providerMetadata: null,
latestVersion: 1,
description: null,
lastResolvedAt: null,
lastRotatedAt: null,
deletedAt: null,
createdByAgentId: null,
createdByUserId: null,
createdAt: new Date("2026-04-01T00:00:00.000Z"),
updatedAt: new Date("2026-04-01T00:00:00.000Z"),
},
{
id: "secret-2",
companyId: "company-1",
key: "new_token",
name: "new-token",
provider: "local_encrypted",
status: "active",
managedMode: "paperclip_managed",
externalRef: null,
providerConfigId: null,
providerMetadata: null,
latestVersion: 1,
description: null,
lastResolvedAt: null,
lastRotatedAt: null,
deletedAt: null,
createdByAgentId: null,
createdByUserId: null,
createdAt: new Date("2026-04-01T00:00:00.000Z"),
updatedAt: new Date("2026-04-01T00:00:00.000Z"),
},
];
mockRoutinesApi.listRevisions.mockResolvedValue([current, old]);
await render({ secrets });
const oldRow = container.querySelector(
"[data-testid='revision-row-1']",
) as HTMLButtonElement | null;
await act(async () => {
oldRow?.click();
});
await flush();
const compareButton = Array.from(container.querySelectorAll("button")).find(
(button) => button.textContent === "Compare with current",
);
await act(async () => {
compareButton?.click();
});
await flush();
expect(container.textContent).toContain("Env GH_TOKEN secret");
expect(container.textContent).not.toContain("Env GH_TOKEN binding kind");
});
it("invokes onRestored with the restore response so the editor can rehydrate (PAP-3588)", async () => {
const current = createRevision({ id: "revision-2", revisionNumber: 2 });
const old = createRevision({

View file

@ -2,10 +2,15 @@ import { useEffect, useMemo, useState } from "react";
import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
import { History as HistoryIcon, RotateCcw, Search } from "lucide-react";
import type {
CompanySecret,
EnvBinding,
EnvSecretRefBinding,
Routine,
RoutineEnvConfig,
RoutineRevision,
RoutineRevisionSnapshotTriggerV1,
RoutineVariable,
SecretVersionSelector,
} from "@paperclipai/shared";
import {
routinesApi,
@ -33,6 +38,7 @@ import { MarkdownBody } from "./MarkdownBody";
type AgentLookup = Map<string, { id: string; name: string }>;
type ProjectLookup = Map<string, { id: string; name: string }>;
type SecretLookup = Map<string, CompanySecret>;
type DirtyFieldDescriptor = {
key: string;
@ -47,6 +53,7 @@ type Props = {
onSaveEdits: () => void;
agents: AgentLookup;
projects: ProjectLookup;
secrets?: CompanySecret[];
onRestoreSecretMaterials: (response: RestoreRoutineRevisionResponse) => void;
onRestored?: (response: RestoreRoutineRevisionResponse) => void;
};
@ -59,9 +66,14 @@ export function RoutineHistoryTab({
onSaveEdits,
agents,
projects,
secrets,
onRestoreSecretMaterials,
onRestored,
}: Props) {
const secretLookup = useMemo<SecretLookup>(
() => new Map((secrets ?? []).map((secret) => [secret.id, secret])),
[secrets],
);
const queryClient = useQueryClient();
const { pushToast } = useToastActions();
const [selectedRevisionId, setSelectedRevisionId] = useState<string | null>(null);
@ -277,6 +289,10 @@ export function RoutineHistoryTab({
selectedRevision,
currentRevision,
)}
envDiffCounts={summarizeEnvDiffCounts(
currentRevision.snapshot.routine.env ?? null,
selectedRevision.snapshot.routine.env ?? null,
)}
/>
)}
@ -289,6 +305,7 @@ export function RoutineHistoryTab({
initialNewRevisionId={currentRevision.id}
agents={agents}
projects={projects}
secrets={secretLookup}
onRestore={(rev) => {
setSelectedRevisionId(rev.id);
setDiffOpen(false);
@ -498,6 +515,10 @@ function RevisionPreview({
highlighted ? "border-emerald-500/40 bg-emerald-500/10" : "border-border"
}`;
const envSummary = summarizeEnv(snapshot.env ?? null);
const envDiffers = !!currentSnapshot
&& JSON.stringify(normalizeEnv(currentSnapshot.env ?? null))
!== JSON.stringify(normalizeEnv(snapshot.env ?? null));
const fieldRows: Array<{ key: string; label: string; value: string; differs: boolean }> = [
{
key: "title",
@ -541,6 +562,12 @@ function RevisionPreview({
value: snapshot.catchUpPolicy.replaceAll("_", " "),
differs: !!currentSnapshot && currentSnapshot.catchUpPolicy !== snapshot.catchUpPolicy,
},
{
key: "env",
label: "Env",
value: envSummary,
differs: envDiffers,
},
];
return (
@ -670,6 +697,7 @@ function RestoreConfirmDialog({
onConfirm,
pending,
recreatedWebhookLabels,
envDiffCounts,
}: {
open: boolean;
onOpenChange: (open: boolean) => void;
@ -680,6 +708,7 @@ function RestoreConfirmDialog({
onConfirm: () => void;
pending: boolean;
recreatedWebhookLabels: string[];
envDiffCounts: EnvDiffCounts;
}) {
const newRevisionNumber = currentRevisionNumber + 1;
return (
@ -698,6 +727,12 @@ function RestoreConfirmDialog({
<span className="mt-1 inline-block h-1.5 w-1.5 rounded-full bg-emerald-400" />
Routine field values, variables, and schedule cron will revert.
</li>
{envDiffCounts.total > 0 && (
<li className="flex items-start gap-2">
<span className="mt-1 inline-block h-1.5 w-1.5 rounded-full bg-emerald-400" />
Routine secrets will revert: {formatEnvDiffCounts(envDiffCounts)}.
</li>
)}
<li className="flex items-start gap-2">
<span className="mt-1 inline-block h-1.5 w-1.5 rounded-full bg-emerald-400" />
Previous run history is preserved.
@ -743,6 +778,7 @@ function RoutineRevisionDiffModal({
initialNewRevisionId,
agents,
projects,
secrets,
onRestore,
}: {
open: boolean;
@ -752,6 +788,7 @@ function RoutineRevisionDiffModal({
initialNewRevisionId: string;
agents: AgentLookup;
projects: ProjectLookup;
secrets: SecretLookup;
onRestore: (revision: RoutineRevision) => void;
}) {
const [leftId, setLeftId] = useState<string>(initialOldRevisionId);
@ -767,8 +804,8 @@ function RoutineRevisionDiffModal({
const left = revisions.find((r) => r.id === leftId) ?? null;
const right = revisions.find((r) => r.id === rightId) ?? null;
const fieldChanges = useMemo(
() => (left && right ? computeFieldChanges(left, right, agents, projects) : []),
[left, right, agents, projects],
() => (left && right ? computeFieldChanges(left, right, agents, projects, secrets) : []),
[left, right, agents, projects, secrets],
);
const descriptionDiff = useMemo<DiffRow[]>(
() => (left && right
@ -1003,6 +1040,7 @@ function computeFieldChanges(
right: RoutineRevision,
agents: AgentLookup,
projects: ProjectLookup,
secrets: SecretLookup,
): Array<{ field: string; oldValue: string | null; newValue: string | null }> {
const oldRoutine = left.snapshot.routine;
const newRoutine = right.snapshot.routine;
@ -1042,10 +1080,170 @@ function computeFieldChanges(
newValue: summarizeVariables(newRoutine.variables),
});
}
compareEnv(oldRoutine.env ?? null, newRoutine.env ?? null, secrets, changes);
compareTriggers(left.snapshot.triggers, right.snapshot.triggers, changes);
return changes;
}
function normalizeEnv(env: RoutineEnvConfig | null): Record<string, EnvBinding> {
if (!env) return {};
return env;
}
function envBindingKind(binding: EnvBinding): "plain" | "secret_ref" {
if (typeof binding === "string") return "plain";
if (binding && typeof binding === "object" && "type" in binding && binding.type === "secret_ref") {
return "secret_ref";
}
return "plain";
}
function asSecretRef(binding: EnvBinding): EnvSecretRefBinding | null {
if (typeof binding === "string") return null;
if (binding && typeof binding === "object" && "type" in binding && binding.type === "secret_ref") {
return binding;
}
return null;
}
function formatVersionSelector(version: SecretVersionSelector | undefined): string {
if (version == null || version === "latest") return "latest";
return `v${version}`;
}
function describeSecretRef(ref: EnvSecretRefBinding, secrets: SecretLookup): string {
const secret = secrets.get(ref.secretId);
const name = secret?.name ?? "<missing-secret>";
return `${name} ${formatVersionSelector(ref.version)}`;
}
function describeEnvBinding(binding: EnvBinding | undefined, secrets: SecretLookup): string {
if (binding === undefined) return "—";
const ref = asSecretRef(binding);
if (ref) return `secret_ref → ${describeSecretRef(ref, secrets)}`;
return "plain (set)";
}
function summarizeEnv(env: RoutineEnvConfig | null): string {
const entries = Object.entries(normalizeEnv(env));
if (entries.length === 0) return "";
const secretCount = entries.filter(([, binding]) => envBindingKind(binding) === "secret_ref").length;
const keyLabel = entries.length === 1 ? "key" : "keys";
if (secretCount === 0) return `${entries.length} ${keyLabel}`;
return `${entries.length} ${keyLabel} (${secretCount} secret ${secretCount === 1 ? "ref" : "refs"})`;
}
type EnvDiffCounts = {
added: number;
removed: number;
changed: number;
total: number;
};
function summarizeEnvDiffCounts(
current: RoutineEnvConfig | null,
target: RoutineEnvConfig | null,
): EnvDiffCounts {
const currentRec = normalizeEnv(current);
const targetRec = normalizeEnv(target);
let added = 0;
let removed = 0;
let changed = 0;
const keys = new Set<string>([...Object.keys(currentRec), ...Object.keys(targetRec)]);
for (const key of keys) {
const inCurrent = key in currentRec;
const inTarget = key in targetRec;
if (inTarget && !inCurrent) {
added += 1;
continue;
}
if (!inTarget && inCurrent) {
removed += 1;
continue;
}
if (JSON.stringify(currentRec[key]) !== JSON.stringify(targetRec[key])) {
changed += 1;
}
}
return { added, removed, changed, total: added + removed + changed };
}
function formatEnvDiffCounts(counts: EnvDiffCounts): string {
const parts: string[] = [];
if (counts.added > 0) parts.push(`${counts.added} ${counts.added === 1 ? "key" : "keys"} added`);
if (counts.removed > 0) parts.push(`${counts.removed} ${counts.removed === 1 ? "key" : "keys"} removed`);
if (counts.changed > 0) parts.push(`${counts.changed} ${counts.changed === 1 ? "key" : "keys"} changed`);
return parts.join(", ");
}
function compareEnv(
oldEnv: RoutineEnvConfig | null,
newEnv: RoutineEnvConfig | null,
secrets: SecretLookup,
changes: Array<{ field: string; oldValue: string | null; newValue: string | null }>,
) {
const oldRec = normalizeEnv(oldEnv);
const newRec = normalizeEnv(newEnv);
const keys = new Set<string>([...Object.keys(oldRec), ...Object.keys(newRec)]);
const sortedKeys = [...keys].sort();
for (const key of sortedKeys) {
const oldBinding = oldRec[key];
const newBinding = newRec[key];
const inOld = key in oldRec;
const inNew = key in newRec;
if (inNew && !inOld) {
changes.push({
field: `Env added (${key})`,
oldValue: "—",
newValue: describeEnvBinding(newBinding, secrets),
});
continue;
}
if (!inNew && inOld) {
changes.push({
field: `Env removed (${key})`,
oldValue: describeEnvBinding(oldBinding, secrets),
newValue: "—",
});
continue;
}
if (JSON.stringify(oldBinding) === JSON.stringify(newBinding)) continue;
const oldKind = envBindingKind(oldBinding);
const newKind = envBindingKind(newBinding);
if (oldKind !== newKind) {
changes.push({
field: `Env ${key} binding kind`,
oldValue: describeEnvBinding(oldBinding, secrets),
newValue: describeEnvBinding(newBinding, secrets),
});
continue;
}
if (newKind === "secret_ref") {
const oldRef = asSecretRef(oldBinding)!;
const newRef = asSecretRef(newBinding)!;
if (oldRef.secretId !== newRef.secretId) {
changes.push({
field: `Env ${key} secret`,
oldValue: describeEnvBinding(oldBinding, secrets),
newValue: describeEnvBinding(newBinding, secrets),
});
continue;
}
changes.push({
field: `Env ${key} version`,
oldValue: describeSecretRef(oldRef, secrets),
newValue: describeSecretRef(newRef, secrets),
});
continue;
}
changes.push({
field: `Env ${key} value`,
oldValue: "plain (set)",
newValue: "plain (changed)",
});
}
}
function summarizeVariables(variables: RoutineVariable[]): string {
if (variables.length === 0) return "(none)";
return variables