fix: show instruction saves in history, credit the real writer, and speed up the agent tool-rule list (#19515)

## Thinking Path

> - Paperclip is the open source app people use to manage AI agents for
work
> - Operators and agents change agent instructions (AGENTS.md), and they
must see who changed them and when
> - Agent files replaced instruction revisions. Saves no longer write
revision rows, so instruction history is empty
> - The current revision is stamped with the reader and the date
1970-01-01, so it gives false audit data
> - Separately, an agent that lists tool rules gets a timeout when many
rules name the same resources
> - This pull request reads history from the save records that Paperclip
already writes, credits the real writer, and checks each tool-rule
resource one time
> - The benefit is a correct audit trail for instruction changes and a
tool-rule list that agents can read

## Linked Issues or Issue Description

No public issue exists. I searched open and closed issues and PRs for
these problems and found none.

**What happened?**
1. `get_agent_instruction_history` (and the history API) returns 0
revisions for an agent whose AGENTS.md was saved many times. The
activity log shows each save as `agent.files_updated` with the path,
content hash, actor and run.
2. `read_agent_instructions` returns a current revision with `createdAt`
1970-01-01. Its actor is the agent that reads it, and its `sourceRunId`
is the run that reads it.
3. `GET /api/companies/{companyId}/tools/policies` from an agent fails
with a transport timeout most of the time when the company has many tool
rules. A board user gets the list without a problem.

**Expected behavior**
1. History lists each save, newest first, with its writer, run, source
and time.
2. The current revision names the agent or user that wrote those bytes,
and the time of that save. If no save is recorded, it names no writer.
3. The agent gets the tool-rule list in normal time, with the same rules
hidden as before.

**Steps to reproduce**
1. Save an agent's instruction entry file (board editor,
`update_agent_instructions`, or a run that edits the file). Read the
history. It is empty.
2. As a different agent, call `read_agent_instructions` on that agent.
The revision shows the reader and 1970-01-01.
3. Create about 40 tool rules that name the same connection and agent.
As an agent, list `/tools/policies`. Each rule does a new set of access
checks for each resource, one after another.

**Paperclip version or commit**
`master` at `819420a60a`.

**Deployment mode**
Hosted. The new tests reproduce all 3 problems on `master`.

## What Changed

- `agent-instruction-revisions.ts`: history merges the legacy revision
rows with the `agent.files_updated` save records for the entry file. The
order is `(created_at, id)` descending, and cursors keep PostgreSQL
timestamp precision.
- `agent-instruction-revisions.ts`: the current revision takes its
writer, run, source and time from the latest save of the same content
hash. A reader is never the writer. Bytes with no save record have no
writer.
- `agent-instruction-revisions.ts`: an identical re-save over bytes with
no record is marked `source: "adopted"`. It repairs the runtime journal
but is not listed as a save.
- `agent-instruction-revisions.ts`: a history ID can be a legacy
revision, a save record, or the current content token. A save record
keeps only metadata. If its bytes are no longer current, a read returns
404 with `INSTRUCTION_REVISION_CONTENT_NOT_RETAINED`.
- `agent-file-store.ts`: saves record `byteLength`. A run collection
that changes the entry file records its path, hash and size, so history
shows saves from runs.
- `connection-management-authz.ts`: `filterConnectionManagementPolicies`
keeps one read decision for each distinct resource in a request, and
loads each application or catalog entry one time. A rule is still hidden
when any resource that it names is hidden. Board callers do not use this
path.
- Tests: new tests for save history, paging, writer credit, adoption,
and the tool-rule list. Old assertions that expected empty history now
check the exact saves.

## Verification

- `pnpm --filter @paperclipai/server exec vitest run
src/__tests__/agent-instruction-revisions.test.ts
src/__tests__/agent-instruction-working-copies.test.ts
src/__tests__/agent-directory-working-copies.test.ts
src/__tests__/built-in-agents.test.ts
src/services/native-runtime/agent-instruction-tools.integration.test.ts
src/__tests__/tool-policy-list-authz.integration.test.ts`
- With the fix: all pass (revisions: 28 passed, 1 skipped on Linux;
other 5 files: 230 passed).
  - With the new tests on `master` code: 13 tests fail, as expected.
- `src/__tests__/connection-management.integration.test.ts`: 90 passed.
- The new tool-rule test lists 40 rules that name 1 connection and
counts the connection reads. It needs fewer than 10.
- I could not run the full server typecheck in my sandbox because of a
memory limit. CI runs it.
- CI on head `a2f0b825`: all checks pass, including `ci / verify` and
`ci / e2e`.

## Risks

- History now shows entries whose ID is an activity row ID, not a
revision row ID. Clients that read or restore an older save get a clear
404 because Paperclip no longer keeps those bytes. The latest save and
legacy revisions still read and restore as before.
- Saves recorded before this change have no `byteLength`. For those,
history shows the current size when the hash matches, and 0 otherwise.
- Stock updates of built-in agents do not record a file path, so they do
not show in history.
- No migration. No change to the stored data model.

> 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

- Anthropic Claude Opus 5.5 (`claude-opus-5-5`), in Claude Code with
tool use (shell, file edits, test runs). Standard context window.

## 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 searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [x] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [ ] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge

🤖 Generated with [Claude Code](https://claude.com/claude-code)

---------

Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com>
Co-authored-by: lucktastic <13757243+lucktastic@users.noreply.github.com>
This commit is contained in:
authored and GitHub committed 2026-11-18 16:41:53 -08:00
1 parent 75ae377438
commit e2cee049f9
13 files changed
+462 -93

No files matched your search

@@ -166,6 +166,21 @@ describe("agent file restore locking", () => {
expect(await stagingLeftovers()).toEqual([]);
});
it.each(["history", "revision"] as const)("a %s read downloads a stale projection without holding the agent row lock", async (operation) => {
const service = agentInstructionRevisionService(db);
const current = await service.readCurrent(target(), board());
await loseLocalProjection();
objects.probe = agentRowLocked;
if (operation === "history") {
await expect(service.history({ ...target(), entryFile }, board())).resolves.toMatchObject({ revisions: expect.any(Array) });
} else {
await expect(service.readRevision({ ...target(), entryFile, revisionId: current!.revision.id }, board()))
.resolves.toMatchObject({ content: "# Policy\n" });
}
expect(objects.downloads).toEqual([{ objectKey: expect.any(String), agentRowLocked: false }]);
expect(await stagingLeftovers()).toEqual([]);
});
it("lets a writer commit during the download and then serves the writer's head, not the stale download", async () => {
await loseLocalProjection();
let open!: () => void, reached!: () => void;
@@ -151,10 +151,8 @@ describe("canonical instruction revisions", () => {
await db.insert(principalPermissionGrants).values({ companyId, principalType: "agent", principalId: actorId, permissionKey: "agents:configure", scope: { agentIds: [actorId] } });
await expect(access()).rejects.toMatchObject({ status: 403 });
await db.update(principalPermissionGrants).set({ scope: { agentIds: [agentId] } }).where(eq(principalPermissionGrants.principalId, actorId));
// New saves have no historical revision row; authorized history lookups
// reach the normal not-found response rather than an authorization denial.
if (operation === "revision" || operation === "diff") await expect(access()).rejects.toMatchObject({ status: 404 });
else await expect(access()).resolves.toBeDefined();
// The current content ETag is readable as a revision once access is granted.
await expect(access()).resolves.toBeDefined();
});
it("allows self and board reads without requiring instruction edit permission", async () => {
await db.delete(principalPermissionGrants).where(eq(principalPermissionGrants.principalId, userId));
@@ -171,9 +169,62 @@ describe("canonical instruction revisions", () => {
expect(saved).toMatchObject({ changed: true, materialization: "current" });
expect(await fs.readFile(path.join(root, entryFile), "utf8")).toBe(saved.content);
expect((await save(saved.content, first.revision.id)).changed).toBe(false);
expect((await service.history({ ...target(), entryFile }, actor)).revisions).toHaveLength(0);
expect((await service.history({ ...target(), entryFile }, actor)).revisions).toHaveLength(1);
expect(await db.select().from(agentInstructionRevisions).where(eq(agentInstructionRevisions.agentId, agentId))).toHaveLength(0);
});
it("names the writer, run and save time of the current bytes, never the reader", async () => {
const board = { type: "board", userId, source: "session" } as const;
const unrecorded = await base();
expect(unrecorded.revision).toMatchObject({ actorAgentId: null, actorUserId: null, responsibleUserId: null, sourceRunId: null });
const saved = await save("# Saved by the writer\n", unrecorded.revision.id);
expect(saved.revision).toMatchObject({ actorAgentId: actorId, sourceRunId: runId, responsibleUserId: userId });
expect(new Date(saved.revision.createdAt).getTime()).toBeGreaterThan(0);
const read = (await service.readCurrent(target(), board))!;
expect(read.revision).toMatchObject({ id: saved.revision.id, actorAgentId: actorId, actorUserId: null, sourceRunId: runId,
responsibleUserId: userId, createdAt: saved.revision.createdAt });
// An identical re-send by another writer does not take over the save.
const resent = await service.commit({ ...target(), entryFile, content: saved.content, baseRevisionId: saved.revision.id, source: "board" }, board);
expect(resent).toMatchObject({ changed: false, revision: { actorAgentId: actorId, sourceRunId: runId, createdAt: saved.revision.createdAt } });
});
it("records an identical save over unrecorded bytes as an adoption, not a save", async () => {
const first = await base();
const adopted = await save(first.content, first.revision.id);
expect(adopted).toMatchObject({ changed: false, revision: { actorAgentId: null, sourceRunId: null } });
expect((await service.history({ ...target(), entryFile }, actor)).revisions).toEqual([]);
expect((await base()).revision).toMatchObject({ actorAgentId: null, sourceRunId: null });
});
it("lists every save newest first with its writer and pages through them", async () => {
const board = { type: "board", userId, source: "session" } as const;
const first = await base();
const one = await save("one", first.revision.id);
const two = await service.commit({ ...target(), entryFile, content: "two", baseRevisionId: one.revision.id, source: "board" }, board);
const three = await service.commit({ ...target(), entryFile, content: "three", baseRevisionId: two.revision.id, source: "tool" }, actor);
const all = await service.history({ ...target(), entryFile }, board);
expect(all.nextCursor).toBeNull();
expect(all.revisions.map(revision => [revision.contentHash, revision.source, revision.actorAgentId, revision.actorUserId, revision.sourceRunId])).toEqual([
[three.revision.contentHash, "tool", actorId, null, runId],
[two.revision.contentHash, "board", null, userId, null],
[one.revision.contentHash, "cleanup", actorId, null, runId],
]);
expect(all.revisions.map(revision => revision.createdAt)).toEqual([three, two, one].map(receipt => receipt.revision.createdAt));
expect(all.revisions.map(revision => revision.byteLength)).toEqual([5, 3, 3]);
const pages = [];
let cursor: string | undefined;
do {
const page = await service.history({ ...target(), entryFile, cursor, limit: 1 }, board);
pages.push(...page.revisions.map(revision => revision.id));
cursor = page.nextCursor ?? undefined;
} while (cursor);
expect(pages).toEqual(all.revisions.map(revision => revision.id));
// The latest save is still the current content; older saves keep metadata only.
expect(await service.readRevision({ ...target(), entryFile, revisionId: all.revisions[0]!.id }, board)).toMatchObject({ content: "three" });
await expect(service.readRevision({ ...target(), entryFile, revisionId: all.revisions[2]!.id }, board))
.rejects.toMatchObject({ status: 404, details: { code: "INSTRUCTION_REVISION_CONTENT_NOT_RETAINED" } });
await expect(service.restore({ ...target(), entryFile, baseRevisionId: three.revision.id, revisionId: all.revisions[2]!.id }, board))
.rejects.toMatchObject({ status: 404 });
expect(await service.diff({ ...target(), entryFile, fromRevisionId: all.revisions[0]!.id, toRevisionId: three.revision.id }, board))
.toMatchObject({ added: "", removed: "" });
});
it("requires a matching initial content token and serializes competing saves", async () => {
await expect(save("without reading", null)).rejects.toMatchObject({ status: 409 });
const first = await base();
@@ -0,0 +1,85 @@
import fs from "node:fs/promises";
import os from "node:os";
import path from "node:path";
import { randomUUID } from "node:crypto";
import { afterAll, beforeAll, beforeEach, describe, expect, it } from "vitest";
import { agents, authUsers, companies, companyMemberships, createDb, heartbeatRuns, principalPermissionGrants } from "@paperclipai/db";
import { startEmbeddedPostgresTestDatabase } from "./helpers/embedded-postgres.js";
import { agentFileStore, snapshotAgentFiles } from "../services/agent-file-store.js";
import { agentInstructionRevisionService } from "../services/agent-instruction-revisions.js";
import { resolveManagedInstructionsRoot } from "../services/agent-instructions.js";
import type { AuthorizationActor } from "../services/authorization.js";
describe("instruction save history", () => {
let database: Awaited<ReturnType<typeof startEmbeddedPostgresTestDatabase>>;
let db: ReturnType<typeof createDb>;
let service: ReturnType<typeof agentInstructionRevisionService>;
const previousHome = process.env.PAPERCLIP_HOME;
let home: string;
let companyId: string, agentId: string, userId: string, actorId: string, root: string;
const entryFile = "AGENTS.md";
async function writer() {
const runId = randomUUID();
await db.insert(heartbeatRuns).values({ id: runId, companyId, agentId: actorId, invocationSource: "on_demand", responsibleUserId: userId });
return { runId, actor: { type: "agent", companyId, agentId: actorId, runId, source: "agent_jwt" } as AuthorizationActor };
}
beforeAll(async () => {
home = await fs.realpath(await fs.mkdtemp(path.join(os.tmpdir(), "instruction-save-history-")));
process.env.PAPERCLIP_HOME = home;
database = await startEmbeddedPostgresTestDatabase("instruction-save-history-db-");
db = createDb(database.connectionString);
service = agentInstructionRevisionService(db);
}, 90_000);
afterAll(async () => {
if (previousHome === undefined) delete process.env.PAPERCLIP_HOME; else process.env.PAPERCLIP_HOME = previousHome;
await database?.cleanup();
if (home) await fs.rm(home, { recursive: true, force: true });
});
beforeEach(async () => {
companyId = randomUUID(); agentId = randomUUID(); actorId = randomUUID(); userId = randomUUID();
await db.insert(companies).values({ id: companyId, name: "Save history", issuePrefix: randomUUID().slice(0, 8) });
await db.insert(authUsers).values({ id: userId, name: "Editor", email: `${userId}@example.test`, createdAt: new Date(), updatedAt: new Date() });
root = resolveManagedInstructionsRoot({ id: agentId, companyId, name: "Target", adapterConfig: {} });
await db.insert(agents).values([
{ id: agentId, companyId, name: "Target", adapterConfig: { instructionsBundleMode: "managed", instructionsRootPath: root, instructionsEntryFile: entryFile } },
{ id: actorId, companyId, name: "Writer" },
]);
await db.insert(companyMemberships).values([
{ companyId, principalType: "user", principalId: userId, membershipRole: "operator" },
{ companyId, principalType: "agent", principalId: actorId, membershipRole: "member" },
]);
await db.insert(principalPermissionGrants).values([
{ companyId, principalType: "user", principalId: userId, permissionKey: "agents:configure", scope: { agentIds: [agentId] } },
{ companyId, principalType: "agent", principalId: actorId, permissionKey: "agents:configure", scope: { agentIds: [agentId] } },
]);
await fs.mkdir(root, { recursive: true });
await fs.writeFile(path.join(root, entryFile), "# Original\n");
});
const target = () => ({ companyId, agentId });
it("accepts the latest save from history as the base of the next edit", async () => {
const { actor } = await writer();
const first = (await service.readCurrent(target(), actor))!;
await service.commit({ ...target(), entryFile, content: "# Saved\n", baseRevisionId: first.revision.id, source: "tool" }, actor);
const [latest] = (await service.history({ ...target(), entryFile }, actor)).revisions;
const read = await service.readRevision({ ...target(), entryFile, revisionId: latest!.id }, actor);
expect(read).toMatchObject({ content: "# Saved\n", revision: { id: latest!.id } });
const edited = await service.commit({ ...target(), entryFile, content: "# Edited\n", baseRevisionId: read.revision.id, source: "tool" }, actor);
expect(edited).toMatchObject({ changed: true, content: "# Edited\n" });
});
it("keeps the first run as the writer when a later run collects the same bytes", async () => {
const baseline = await snapshotAgentFiles(root);
const runs = [await writer(), await writer()];
const store = agentFileStore(db);
for (const run of runs) {
const sourceDir = path.join(home, `run-${run.runId}`);
await fs.cp(root, sourceDir, { recursive: true });
await fs.writeFile(path.join(sourceDir, entryFile), "# Same edit from two runs\n");
await store.apply({ companyId, agentId, sourceDir, baseline }, run.actor);
}
const { revisions } = await service.history({ ...target(), entryFile }, runs[0]!.actor);
expect(revisions).toEqual([expect.objectContaining({ actorAgentId: actorId, sourceRunId: runs[0]!.runId })]);
expect((await service.readCurrent(target(), runs[0]!.actor))!.revision).toMatchObject({ sourceRunId: runs[0]!.runId });
});
});
@@ -631,7 +631,7 @@ describe("registered run instruction copies", () => {
expect(await fs.readFile(path.join(root, entryFile), "utf8")).toBe(edited);
copies = agentInstructionWorkingCopyService(db);
expect((await copies.collectStopped({ companyId, runId: copy.runId }))?.receipt).toEqual(saved?.receipt);
expect((await revisions.history({ ...target(), entryFile }, board())).revisions).toHaveLength(0);
expect((await revisions.history({ ...target(), entryFile }, board())).revisions).toEqual([expect.objectContaining({ actorAgentId: agentId, sourceRunId: copy.runId })]);
const next = await run();
expect(await fs.readFile(path.join(next.localRoot, entryFile), "utf8")).toBe(edited);
});
@@ -733,7 +733,8 @@ describe("registered run instruction copies", () => {
await makeRemovable(context.instructions.bundle.rootPath);
}
expect(await fs.readFile(path.join(root, entryFile), "utf8")).toBe("current filesystem contents");
expect((await revisions.history({ ...target(), entryFile }, board())).revisions).toHaveLength(0);
// Only the run's save is recorded; a direct filesystem write names no writer.
expect((await revisions.history({ ...target(), entryFile }, board())).revisions).toEqual([expect.objectContaining({ actorAgentId: agentId, sourceRunId: copy.runId })]);
await expect(revisions.readCommittedForRuntime({ companyId: randomUUID(), agentId })).rejects.toThrow("Agent not found");
});
@@ -837,7 +838,8 @@ describe("registered run instruction copies", () => {
await fs.writeFile(path.join(duplicate.localRoot, entryFile), "one final edit");
await Promise.all([copies.collectStopped({ companyId, runId: duplicate.runId }), copies.collectStopped({ companyId, runId: duplicate.runId })]);
expect((await copies.get(companyId, duplicate.runId))?.state).toBe("saved");
expect((await revisions.history({ ...target(), entryFile }, board())).revisions).toHaveLength(0);
expect((await revisions.history({ ...target(), entryFile }, board())).revisions).toEqual([
expect.objectContaining({ sourceRunId: duplicate.runId }), expect.objectContaining({ sourceRunId: copy.runId })]);
});
it("requires durable stop evidence before recovering an uncaptured copy", async () => {
const copy = await run();
@@ -677,6 +677,22 @@ describe("agent instructions bundle routes", () => {
expect(mockInstructionRevisions.restore).toHaveBeenCalledWith({ companyId: "company-1", agentId: "11111111-1111-4111-8111-111111111111", entryFile: "AGENTS.md", revisionId, baseRevisionId }, expect.objectContaining({ type: "board", userId: "local-board" }));
});
it("opens a listed save against the current content token", async () => {
const app = await createApp();
const saveId = "33333333-3333-4333-8333-333333333333";
// The current content token is a version-8 UUID derived from the file hash.
const currentToken = "0f3c9a1e-7b2d-8e4f-a1b2-c3d4e5f60718";
const prefix = "/api/agents/11111111-1111-4111-8111-111111111111/instructions-bundle";
mockInstructionRevisions.diff.mockResolvedValue({ removed: "old", added: "new" });
mockInstructionRevisions.readRevision.mockResolvedValue({ revision: { id: currentToken, entryFile: "AGENTS.md", byteLength: 3 }, content: "new" });
expect((await requestApp(app, (url) => request(url).get(`${prefix}/diff?path=AGENTS.md&from=${saveId}&to=${currentToken}`))).status).toBe(200);
expect(mockInstructionRevisions.diff).toHaveBeenCalledWith(expect.objectContaining({ fromRevisionId: saveId, toRevisionId: currentToken }), expect.anything());
expect((await requestApp(app, (url) => request(url).get(`${prefix}/revision/${currentToken}?path=AGENTS.md`))).status).toBe(200);
expect(mockInstructionRevisions.readRevision).toHaveBeenCalledWith(expect.objectContaining({ revisionId: currentToken }), expect.anything());
expect((await requestApp(app, (url) => request(url).get(`${prefix}/diff?path=AGENTS.md&from=${saveId}&to=not-a-revision`))).status).toBe(422);
expect((await requestApp(app, (url) => request(url).get(`${prefix}/revision/0f3c9a1e-7b2d-9e4f-a1b2-c3d4e5f60718?path=AGENTS.md`))).status).toBe(422);
});
it("requires a base revision and rejects client-supplied responsible identity", async () => {
const app = await createApp();
for (const body of [ { path: "AGENTS.md", content: "stale" }, { path: "AGENTS.md", content: "forged", baseRevisionId: null, responsibleUserId: "forged" } ]) {
+1 -1
View File
@@ -1033,9 +1033,9 @@ describeEmbeddedPostgres("built-in agents", () => {
const revisions = agentInstructionRevisionService(db);
const target = { companyId, agentId: created.agent!.id, entryFile: "AGENTS.md" };
const history = await revisions.history(target, instructionOperator);
expect(history.revisions).toHaveLength(0);
const current = await revisions.readCurrent(target, instructionOperator);
expect(current?.content).toBe(resetFile.content);
expect(history.revisions[0]).toMatchObject({ contentHash: current!.revision.contentHash, createdAt: current!.revision.createdAt });
});
it("blocks deleting a built-in agent", async () => {
@@ -0,0 +1,92 @@
import { randomUUID } from "node:crypto";
import { join } from "node:path";
import { eq } from "drizzle-orm";
import { afterAll, beforeAll, describe, expect, it, vi } from "vitest";
import { companies, heartbeatRuns, issues, toolConnections } from "@paperclipai/db";
import { startRunnerApiTestServer } from "./helpers/runner-api-server.js";
import { configureAgentLifecycle } from "../services/agent-lifecycle.js";
import { agentService } from "../services/agents.js";
import { accessService } from "../services/access.js";
vi.mock("../services/agent-lifecycle-driver.js", () => ({
createLifecycleDriver: () => ({ requiredPluginIds: async () => [], runPlugin: async () => "complete", runHost: async () => "complete" }),
}));
// Requests traverse the assembled server and production bearer middleware.
describe("tool policy list for agent callers", () => {
let server: Awaited<ReturnType<typeof startRunnerApiTestServer>>;
let lifecycle: ReturnType<typeof configureAgentLifecycle>;
let externalFetch: ReturnType<typeof vi.spyOn>;
beforeAll(async () => {
vi.stubEnv("PAPERCLIP_AGENT_JWT_SECRET", randomUUID());
vi.stubEnv("PAPERCLIP_RESPONSIBLE_USER_AUTHZ_MODE", "shadow");
vi.stubEnv("PAPERCLIP_AUTH_RATE_LIMIT_ENABLED", "false");
const realFetch = globalThis.fetch;
externalFetch = vi.spyOn(globalThis, "fetch").mockImplementation((input, init) => {
if (new URL(String(input)).hostname === "127.0.0.1") return realFetch(input, init);
throw new Error("Unexpected external request in policy list fixture");
});
server = await startRunnerApiTestServer({ authPublicBaseUrl: "https://paperclip.fixture.invalid", humanSessions: true });
lifecycle = configureAgentLifecycle(server.db, { requiredPluginIds: async () => [], runPlugin: async () => "complete", runHost: async () => "complete" });
vi.stubEnv("PAPERCLIP_SECRETS_MASTER_KEY_FILE", join(server.root, "master.key"));
}, 90_000);
afterAll(async () => { await lifecycle?.stop(); await server?.close(); externalFetch?.mockRestore(); vi.unstubAllEnvs(); });
async function fixture() {
const base = await server.fixture({ connectionScenario: "fresh" });
const userId = base.responsibleUserId!;
const access = accessService(server.db);
await access.ensureMembership(base.companyId, "user", userId, "operator", "active");
await access.ensureRoleDefaultGrants(base.companyId, userId, "operator", userId);
await server.db.update(companies).set({ requireBoardApprovalForNewAgents: false }).where(eq(companies.id, base.companyId));
const cookie = await server.humanSession(userId);
const created = await fetch(`${server.apiUrl}/api/companies/${base.companyId}/agents`, {
method: "POST", headers: { cookie, "Content-Type": "application/json", origin: server.apiUrl },
body: JSON.stringify({ name: "Policy reader", role: "engineer", adapterType: "paperclip_runner", adapterConfig: { provider: "codex" },
runtimeConfig: { heartbeat: { enabled: false, wakeOnDemand: false } }, permissions: {} }),
});
const agent = await created.json();
expect(created.status, JSON.stringify(agent)).toBe(201);
await lifecycle.process(agent.id);
await vi.waitFor(async () => expect((await agentService(server.db).getById(agent.id))?.status).toBe("idle"), { timeout: 10_000 });
await server.db.update(heartbeatRuns).set({ agentId: agent.id }).where(eq(heartbeatRuns.id, base.runId));
await server.db.update(issues).set({ assigneeAgentId: agent.id, responsibleUserId: userId }).where(eq(issues.id, base.issueId));
const key = await agentService(server.db).createApiKey(agent.id, "integration", { kind: "standard" }, { responsibleUserId: userId });
const request = async (method: string, path: string, body?: unknown) => {
const response = await fetch(`${server.apiUrl}/api${path}`, { method, headers: { Authorization: `Bearer ${key.token}`, "Content-Type": "application/json" }, ...(body === undefined ? {} : { body: JSON.stringify(body) }) });
return { status: response.status, body: await response.json().catch(() => null) };
};
return { ...base, agentId: agent.id as string, request };
}
it("checks each distinct resource once, however many rules name it", async () => {
const f = await fixture();
const connection = await f.request("POST", `/companies/${f.companyId}/tools/connections`, { name: "Shared policy target", transport: "mcp_remote", authKind: "none", transportConfig: { url: "https://1.1.1.1/mcp" } });
expect(connection).toMatchObject({ status: 201 });
const path = `/companies/${f.companyId}/tools/policies`;
const policyIds: string[] = [];
for (let index = 0; index < 40; index++) {
const policy = await f.request("POST", path, { name: `Shared rule ${index}`, policyType: "allow", selectors: { agentId: f.agentId, connectionId: connection.body.id } });
expect(policy).toMatchObject({ status: 201 });
policyIds.push(policy.body.id);
}
let connectionReads = 0;
const originalSelect = server.db.select.bind(server.db);
const select = vi.spyOn(server.db, "select").mockImplementation(((selection: never) => {
const builder = originalSelect(selection);
const originalFrom = builder.from.bind(builder);
builder.from = ((table: never) => {
if (table === toolConnections) connectionReads++;
return originalFrom(table);
}) as typeof builder.from;
return builder;
}) as unknown as typeof server.db.select);
try {
const listed = await f.request("GET", path);
expect(listed).toMatchObject({ status: 200 });
expect((listed.body.policies as Array<{ id: string }>).map(policy => policy.id)).toEqual(expect.arrayContaining(policyIds));
// Checking every rule again made long rule lists exceed the agent API timeout.
expect(connectionReads).toBeLessThan(10);
} finally { select.mockRestore(); }
});
});
+9 -2
View File
@@ -379,6 +379,13 @@ function readRunIssueId(context: Record<string, unknown> | null) {
return typeof nestedIssueId === "string" && isUuidLike(nestedIssueId) ? nestedIssueId : null;
}
// Instruction history IDs are revision or save-record UUIDs, or the current
// content token, which is a version-8 UUID that `isUuidLike` rejects.
const INSTRUCTION_REVISION_ID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
function isInstructionRevisionId(value: string) {
return INSTRUCTION_REVISION_ID_RE.test(value);
}
// Confirms a pre-existing `CODEX_HOME_<handle>` secret still names this
// account's own home before a device login treats the secret's presence as a
// successful, idempotent login. The secret name alone is not proof of a
@@ -5465,7 +5472,7 @@ export function agentRoutes(
if (!existing) return;
assertExternalInstructionsAdmin(req, existing);
const revisionId = req.params.revisionId as string;
if (!isUuidLike(revisionId)) throw unprocessable("Invalid instruction revision id");
if (!isInstructionRevisionId(revisionId)) throw unprocessable("Invalid instruction revision id");
const entryFile = typeof req.query.path === "string" ? req.query.path : deriveBundleState(existing).entryFile;
res.json(await instructionRevisions.readRevision({ companyId: existing.companyId, agentId: existing.id, entryFile, revisionId }, req.actor));
});
@@ -5475,7 +5482,7 @@ export function agentRoutes(
assertExternalInstructionsAdmin(req, existing);
const fromRevisionId = typeof req.query.from === "string" ? req.query.from : "";
const toRevisionId = typeof req.query.to === "string" ? req.query.to : "";
if (!isUuidLike(fromRevisionId) || !isUuidLike(toRevisionId)) throw unprocessable("Provide valid from and to revision ids");
if (!isInstructionRevisionId(fromRevisionId) || !isInstructionRevisionId(toRevisionId)) throw unprocessable("Provide valid from and to revision ids");
const entryFile = typeof req.query.path === "string" ? req.query.path : deriveBundleState(existing).entryFile;
res.json(await instructionRevisions.diff({ companyId: existing.companyId, agentId: existing.id, entryFile, fromRevisionId, toRevisionId }, req.actor));
});
@@ -449,6 +449,17 @@ export async function filterConnectionManagementPolicies<T extends { selectors:
if (req.actor.type !== "agent") return rows;
const context = connectionRequestContext(req);
if (!context) throw forbidden("Connection management authority is required");
// Rules often name the same resources. One read decision per resource keeps
// long rule lists within the agent API timeout.
const service = connectionManagementService(db);
const decisions = new Map<string, Promise<boolean>>();
const applicationConnections = new Map<string, Promise<{ connectionId: string }[]>>();
const catalogConnections = new Map<string, Promise<{ connectionId: string }[]>>();
// Query builders run again on every await; settle each load once.
const once = <V>(cache: Map<string, Promise<V>>, key: string, load: () => PromiseLike<V>) => {
if (!cache.has(key)) cache.set(key, Promise.resolve(load()));
return cache.get(key)!;
};
const visible: T[] = [];
for (const row of rows) {
const resources: Partial<ConnectionManagementResource>[] = [{}];
@@ -456,16 +467,15 @@ export async function filterConnectionManagementPolicies<T extends { selectors:
for (const key of ["connectionId", "profileId", "gatewayId", "projectId", "issueId", "routineId"] as const) for (const id of ids(key)) resources.push({ [key]: id });
for (const id of ids("agentId")) resources.push({ targetAgentId: id });
for (const applicationId of ids("applicationId")) {
const connections = await db.select({ connectionId: toolConnections.id }).from(toolConnections).where(and(eq(toolConnections.applicationId, applicationId), eq(toolConnections.companyId, context.resource.companyId)));
resources.push(...connections);
resources.push(...await once(applicationConnections, applicationId, () => db.select({ connectionId: toolConnections.id }).from(toolConnections).where(and(eq(toolConnections.applicationId, applicationId), eq(toolConnections.companyId, context.resource.companyId)))));
}
for (const id of ids("catalogEntryId")) {
const [entry] = await db.select({ connectionId: toolCatalogEntries.connectionId }).from(toolCatalogEntries).where(and(eq(toolCatalogEntries.id, id), eq(toolCatalogEntries.companyId, context.resource.companyId)));
if (entry) resources.push(entry);
resources.push(...await once(catalogConnections, id, () => db.select({ connectionId: toolCatalogEntries.connectionId }).from(toolCatalogEntries).where(and(eq(toolCatalogEntries.id, id), eq(toolCatalogEntries.companyId, context.resource.companyId)))));
}
let allowed = true;
for (const resource of resources) {
if (!(await connectionManagementService(db).capability(req.actor, "connections:profiles", { ...context.resource, ...resource }, { mutation: false, readContext: context })).allowed) { allowed = false; break; }
const key = JSON.stringify(Object.entries(resource).sort(([a], [b]) => a.localeCompare(b)));
if (!(await once(decisions, key, async () => (await service.capability(req.actor, "connections:profiles", { ...context.resource, ...resource }, { mutation: false, readContext: context })).allowed))) { allowed = false; break; }
}
if (allowed) visible.push(row);
}
+11 -3
View File
@@ -321,7 +321,8 @@ export function agentFileStore(db: Db) {
const currentHash = previous?.hash ?? null;
const incomingHash = input.bytes === null ? null : fileHash(input.bytes);
if (currentHash === incomingHash) {
if (!await isAgentFileSaveRecorded(tx, agent, relative, incomingHash)) await audit(tx, agent, bound, { path: relative, contentHash: incomingHash });
// Bytes already on disk are adopted, not written, by this caller.
if (!await isAgentFileSaveRecorded(tx, agent, relative, incomingHash)) await audit(tx, agent, bound, { path: relative, contentHash: incomingHash, source: "adopted" });
return { contentHash: currentHash, changed: false };
}
if (input.bytes && input.bytes.length <= MAX_INSTRUCTION_BYTES) {
@@ -341,7 +342,7 @@ export function agentFileStore(db: Db) {
}
if (input.bytes === null) await fs.unlink(await assertInstructionPathSafe(root, relative));
else await materializeInstructionBytes(root, relative, input.bytes);
await audit(tx, agent, bound, { path: relative, contentHash: incomingHash, created: previous === null && input.bytes !== null });
await audit(tx, agent, bound, { path: relative, contentHash: incomingHash, created: previous === null && input.bytes !== null, ...(input.bytes ? { byteLength: input.bytes.length } : {}) });
return { contentHash: incomingHash, changed: true };
}, input.bytes && input.bytes.length <= MAX_INSTRUCTION_BYTES ? [input.bytes.toString("utf8")] : []),
apply: async (input: { companyId: string; agentId: string; sourceDir: string; baseline: DirectorySnapshot; checkpoint?: AgentFileManifest }, actor: AuthorizationActor) => {
@@ -430,9 +431,16 @@ export function agentFileStore(db: Db) {
total += size;
}
assertDirectorySize(total, finalEntries.size);
const entryBefore = changed.includes(entryPath) ? await readInstructionBytes(root, entryPath) : null;
await mergeDirectoryWithBaseline({ ...input, baseline: applyBaseline, targetDir: root,
...(input.checkpoint ? { snapshots: { source: incoming, current } } : {}) });
await audit(tx, agent, bound, { sourceRunId: currentPluginInteractionOrigin()?.runId ?? actor.runId, contract: AGENT_FILES_CONTRACT });
// A run that changed the saved instruction entry saved it: name the entry
// and its resulting bytes so instruction history can show this save.
// Bytes another writer already saved stay credited to that writer.
const entryAfter = changed.includes(entryPath) ? await readInstructionBytes(root, entryPath) : null;
const entry = entryAfter && !(entryBefore && entryBefore.equals(entryAfter)) ? entryAfter : null;
await audit(tx, agent, bound, { sourceRunId: currentPluginInteractionOrigin()?.runId ?? actor.runId, contract: AGENT_FILES_CONTRACT,
...(entry ? { path: entryPath, contentHash: fileHash(entry), byteLength: entry.length } : {}) });
return { storageWarning: storageWarning(total, finalEntries.size, fullFile) };
}, [...changedMentions.values()].map(value => value.text), prepared);
},
@@ -6,7 +6,7 @@ import { createHash } from "node:crypto";
import { adoptAgentFiles, agentFileToken, isAgentFileSaveRecorded } from "./agent-file-store.js";
import { withAgentFilesRestoredBeforeLock } from "./agent-file-durability.js";
import { invalidateAgentFileProjection, persistDurableAgentFiles } from "./agent-file-durability.js";
import { and, desc, eq, getTableColumns, lt, or, sql } from "drizzle-orm";
import { and, desc, eq, getTableColumns, inArray, sql } from "drizzle-orm";
import {
activityLog,
agents,
@@ -146,9 +146,9 @@ export function agentInstructionRevisionService(db: Db) {
const state = await lockTarget(tx, target);
const bound = await authorizePluginReset(tx, actor, target, state.agent);
// Preserve the formerly configured entry before an explicit stock reset.
await currentFile(tx, target, state, bound);
const row = await currentFile(tx, target, { ...state, entryFile: bound.declaredEntryFile }, bound);
return { snapshot: row ? snapshot(row) : null, configuredEntryFile: state.entryFile };
await currentFile(tx, target, state);
const row = await currentFile(tx, target, { ...state, entryFile: bound.declaredEntryFile });
return { snapshot: row ? snapshot(await withSaveRecord(tx, row)) : null, configuredEntryFile: state.entryFile };
});
}
async function head(tx: Tx, target: InstructionTarget, entryFile: string) {
@@ -161,34 +161,78 @@ export function agentInstructionRevisionService(db: Db) {
}
// The deployed revision tables are read-only upgrade input. Current bytes
// live in the agent directory; old UUID clients receive a content ETag.
async function currentFile(tx: Tx, target: InstructionTarget, state: Awaited<ReturnType<typeof lockTarget>>, actor?: RevisionActor) {
async function currentFile(tx: Tx, target: InstructionTarget, state: Awaited<ReturnType<typeof lockTarget>>) {
await adoptAgentFiles(tx, state.agent);
const bytes = await readInstructionBytes(state.root, state.entryFile);
if (bytes === null) return null;
return currentRow(target, state.entryFile, bytes, actor);
return currentRow(target, state.entryFile, bytes);
}
function currentRow(target: InstructionTarget, entryFile: string, bytes: Buffer, actor?: RevisionActor): Revision {
const origin = currentPluginInteractionOrigin();
return { ...target, id: agentFileToken(bytes), entryFile, contentBase64: bytes.toString("base64"),
contentHash: createHash("sha256").update(bytes).digest("hex"), byteLength: bytes.length,
parentRevisionId: null, baseRevisionId: null, restoredFromRevisionId: null, source: "api",
...actorFields(actor), createdAt: new Date(0) };
}
// The writer of a commit; a read passes no actor and names no writer.
function actorFields(actor?: RevisionActor) {
const origin = actor ? currentPluginInteractionOrigin() : undefined;
return {
actorAgentId: origin?.agentId ?? (actor?.type === "agent" ? actor.agentId ?? null : null),
actorUserId: origin ? null : actor?.type === "board" ? actor.userId ?? null : null,
responsibleUserId: origin ? null : actor?.type === "board" ? actor.userId ?? null : actor?.type === "agent" ? actor.onBehalfOfUserId ?? null : null,
sourceRunId: origin ? origin.runId ?? null : actor && actor.type !== "plugin" ? actor.runId ?? null : null, createdAt: new Date(0) };
sourceRunId: origin ? origin.runId ?? null : actor && actor.type !== "plugin" ? actor.runId ?? null : null,
};
}
async function getRevision(
tx: Tx,
target: InstructionTarget,
entryFile: string,
id: string,
) {
const [row] = await tx
.select()
.from(revisions)
.where(and(owner(target, entryFile), eq(revisions.id, id)));
if (!row) throw notFound("Instruction revision not found");
return row;
// Every save writes one `agent.files_updated` row with the path and content
// hash. Those rows are the instruction history; adoption rows only repair the
// runtime journal and name nobody as the writer.
function saveRecords(target: InstructionTarget, entryFile: string) {
return and(
eq(activityLog.companyId, target.companyId), eq(activityLog.entityType, "agent"),
eq(activityLog.entityId, target.agentId), eq(activityLog.action, "agent.files_updated"),
eq(sql<string>`${activityLog.details}->>'path'`, entryFile),
sql`${activityLog.details}->>'contentHash' is not null`,
sql`${activityLog.details}->>'source' is distinct from 'adopted'`,
);
}
type SaveRecord = typeof activityLog.$inferSelect;
function saveSource(source: unknown): AgentInstructionSource {
if (source === "legacy_restore") return "restore";
return source === "board" || source === "api" || source === "tool" || source === "cleanup" ? source : "api";
}
function saveRevision(save: SaveRecord, entryFile: string, current: Revision | null): Omit<Revision, "contentBase64"> {
const contentHash = String(save.details!.contentHash);
const byteLength = typeof save.details!.byteLength === "number" ? save.details!.byteLength
: current?.contentHash === contentHash ? current.byteLength : 0;
return { id: save.id, companyId: save.companyId, agentId: save.entityId, entryFile, contentHash, byteLength,
parentRevisionId: null, baseRevisionId: null, restoredFromRevisionId: null, source: saveSource(save.details!.source),
actorAgentId: save.actorType === "agent" ? save.actorId : null,
actorUserId: save.actorType === "user" ? save.actorId : null,
responsibleUserId: save.responsibleUserId, sourceRunId: save.runId, createdAt: save.createdAt };
}
// The content ETag carries no history. Its writer is the latest save of these
// exact bytes, never the reader; bytes with no recorded save have no writer.
async function withSaveRecord(tx: Tx, row: Revision): Promise<Revision> {
const [saved] = await tx.select().from(activityLog)
.where(and(saveRecords(row, row.entryFile), eq(sql<string>`${activityLog.details}->>'contentHash'`, row.contentHash)))
.orderBy(desc(activityLog.createdAt), desc(activityLog.id)).limit(1);
if (!saved) return row;
const { id: _saveId, byteLength: _byteLength, ...writer } = saveRevision(saved, row.entryFile, row);
return { ...row, ...writer, id: row.id, byteLength: row.byteLength };
}
// A history ID is a legacy revision, a save record, or the current content
// ETag. A save's bytes are kept only while they are still current.
async function resolveRevision(tx: Tx, target: InstructionTarget, entryFile: string, id: string, current: Revision | null): Promise<Revision> {
const [legacy] = await tx.select().from(revisions).where(and(owner(target, entryFile), eq(revisions.id, id)));
if (legacy) return legacy;
if (current && current.entryFile === entryFile && current.id === id) return withSaveRecord(tx, current);
const [saved] = await tx.select().from(activityLog).where(and(saveRecords(target, entryFile), eq(activityLog.id, id)));
if (!saved) throw notFound("Instruction revision not found");
if (!current || current.entryFile !== entryFile || current.contentHash !== saved.details!.contentHash) {
throw notFound("This save is in the history, but its content is no longer kept. Only the current content can be read.", {
code: "INSTRUCTION_REVISION_CONTENT_NOT_RETAINED", revisionId: id });
}
return { ...saveRevision(saved, entryFile, current), contentBase64: current.contentBase64 };
}
async function readCurrent(
target: InstructionTarget,
@@ -196,9 +240,9 @@ export function agentInstructionRevisionService(db: Db) {
): Promise<AgentInstructionSnapshot | null> {
return withAgentFilesRestoredBeforeLock(() => db.transaction(async (tx) => {
const state = await lockTarget(tx, target, actor);
const bound = await authorizeRead(tx, actor, target);
const row = await currentFile(tx, target, state, bound);
return row ? snapshot(row) : null;
await authorizeRead(tx, actor, target);
const row = await currentFile(tx, target, state);
return row ? snapshot(await withSaveRecord(tx, row)) : null;
}));
}
/** Trusted orchestration read for the already authorized run target. This
@@ -229,9 +273,11 @@ export function agentInstructionRevisionService(db: Db) {
instructionPath(input.entryFile);
const bytes = "content" in input ? instructionBytes(input.content) : null;
const result = await db.transaction(async (tx) => {
const restoredInput = "restoreRevisionId" in input
? await getRevision(tx, input, input.entryFile, input.restoreRevisionId) : null;
const submittedContent = (bytes ?? Buffer.from(restoredInput!.contentBase64, "base64")).toString("utf8");
// Only a legacy revision can restore new bytes. A save or the current ETag
// restores the current bytes, which resolveRevision checks under the lock.
const [restoredInput] = "restoreRevisionId" in input
? await tx.select().from(revisions).where(and(owner(input, input.entryFile), eq(revisions.id, input.restoreRevisionId))) : [];
const submittedContent = (bytes ?? (restoredInput ? Buffer.from(restoredInput.contentBase64, "base64") : Buffer.alloc(0))).toString("utf8");
await assertAgentInteraction(tx, { companyId: input.companyId, actorAgentId: actor.type === "agent" ? actor.agentId : null,
operation: "configure", targetAgentId: input.agentId, lockAgentIds: extractAgentMentionIds(submittedContent), lock: "update" });
const state = await lockTarget(tx, input, actor.type === "plugin" ? undefined : actor);
@@ -249,14 +295,15 @@ export function agentInstructionRevisionService(db: Db) {
{ code: "INSTRUCTION_ENTRY_CHANGED", entryFile: state.entryFile },
);
await assertInstructionPathSafe(state.root, state.entryFile);
const current = await currentFile(tx, input, state, bound);
const current = await currentFile(tx, input, state);
const restored =
"restoreRevisionId" in input
? await getRevision(
? await resolveRevision(
tx,
input,
input.entryFile,
input.restoreRevisionId,
current,
)
: null;
const candidate = bytes ?? Buffer.from(restored!.contentBase64, "base64");
@@ -265,12 +312,15 @@ export function agentInstructionRevisionService(db: Db) {
operation: "mention", texts: [submittedContent] });
}
const origin = currentPluginInteractionOrigin();
const recordSave = (row: Revision) => tx.insert(activityLog).values({ companyId: input.companyId,
const writer = actorFields(bound);
const recordSave = (row: Revision, adopted: boolean) => tx.insert(activityLog).values({ companyId: input.companyId,
actorType: origin ? "agent" : bound.type === "plugin" ? "plugin" : bound.type === "board" ? "user" : "agent",
actorId: origin?.agentId ?? (bound.type === "plugin" ? bound.pluginId : bound.type === "board" ? bound.userId : bound.agentId)!,
agentId: origin?.agentId ?? (bound.type === "agent" ? bound.agentId : null), runId: row.sourceRunId,
responsibleUserId: row.responsibleUserId, action: "agent.files_updated", entityType: "agent", entityId: input.agentId,
details: { path: input.entryFile, contentHash: row.contentHash, created: current === null, source: restored ? "legacy_restore" : (input as InstructionCommitInput).source } });
agentId: origin?.agentId ?? (bound.type === "agent" ? bound.agentId : null), runId: writer.sourceRunId,
responsibleUserId: writer.responsibleUserId, action: "agent.files_updated", entityType: "agent", entityId: input.agentId,
details: { path: input.entryFile, contentHash: row.contentHash, byteLength: row.byteLength, created: current === null,
source: adopted ? "adopted" : restored ? "legacy_restore" : (input as InstructionCommitInput).source } })
.returning({ createdAt: activityLog.createdAt }).then(([saved]) => saved!.createdAt);
const bindEntry = async () => {
if (
!state.agent.adapterConfig.instructionsRootPath ||
@@ -291,14 +341,19 @@ export function agentInstructionRevisionService(db: Db) {
// An exact replay can safely return the durable receipt even after its base
// advanced. Restore also deduplicates identical content, preserving history.
if (current && current.contentBase64 === candidate.toString("base64")) {
if (!await isAgentFileSaveRecorded(tx, state.agent, input.entryFile, current.contentHash)) await recordSave(current);
// These bytes predate this call. Record the caller's adoption for the
// runtime journal, and answer with the bytes' own writer.
if (!await isAgentFileSaveRecorded(tx, state.agent, input.entryFile, current.contentHash)) await recordSave(current, true);
await bindEntry();
return { row: current, changed: false };
return { row: await withSaveRecord(tx, current), changed: false };
}
// A pre-upgrade run can still pin a historical UUID. Compare its bytes,
// never let the old head project over a newer directory.
// A pre-upgrade run can still pin a historical UUID, and a history read
// returns a save record ID. Compare their bytes, never let an old base
// project over a newer directory.
const legacyBase = input.baseRevisionId && current?.id !== input.baseRevisionId
? await tx.select().from(revisions).where(and(owner(input, input.entryFile), eq(revisions.id, input.baseRevisionId))).then(rows => rows[0])
? await tx.select({ contentHash: revisions.contentHash }).from(revisions).where(and(owner(input, input.entryFile), eq(revisions.id, input.baseRevisionId))).then(rows => rows[0])
?? await tx.select({ contentHash: sql<string>`${activityLog.details}->>'contentHash'` }).from(activityLog)
.where(and(saveRecords(input, input.entryFile), eq(activityLog.id, input.baseRevisionId))).then(rows => rows[0])
: null;
if ((current?.id ?? null) !== input.baseRevisionId && !(legacyBase && legacyBase.contentHash === current?.contentHash)) {
throw conflict(
@@ -314,7 +369,7 @@ export function agentInstructionRevisionService(db: Db) {
await materializeInstructionBytes(state.root, state.entryFile, candidate);
await persistDurableAgentFiles(tx, state.agent, state.root);
const row = currentRow(input, input.entryFile, candidate, bound);
await recordSave(row);
row.createdAt = await recordSave(row, false);
await bindEntry();
return { row, changed: true };
});
@@ -330,60 +385,63 @@ export function agentInstructionRevisionService(db: Db) {
actor: AuthorizationActor,
): Promise<AgentInstructionHistory> {
const limit = Math.max(1, Math.min(100, target.limit ?? 50));
return db.transaction(async (tx) => {
return withAgentFilesRestoredBeforeLock(() => db.transaction(async (tx) => {
const state = await lockTarget(tx, target, actor);
const bound = await authorizeRead(tx, actor, target);
await currentFile(tx, target, state, bound);
instructionPath(target.entryFile);
const cursor = target.cursor
? await getRevision(tx, target, target.entryFile, target.cursor)
: null;
await authorizeRead(tx, actor, target);
const current = await currentFile(tx, target, state);
const entryFile = instructionPath(target.entryFile);
// History merges adopted legacy revision rows with the save records that
// replaced them. Both share one (created_at, id) order.
const entries = sql`(
select ${revisions.id} as id, ${revisions.createdAt} as created_at from ${revisions}
where ${owner(target, entryFile)}
union all
select ${activityLog.id} as id, ${activityLog.createdAt} as created_at from ${activityLog}
where ${saveRecords(target, entryFile)}
) entries`;
if (target.cursor) {
const [known] = await tx.execute<{ id: string }>(sql`select id from ${entries} where id = ${target.cursor}`);
if (!known) throw notFound("Instruction revision not found");
}
// Keep PostgreSQL timestamp precision; JS Date truncates microseconds and
// would skip revisions in the cursor's fractional millisecond.
const cursorTime = cursor
? sql`(select created_at from agent_instruction_revisions where id = ${cursor.id})`
: null;
const rows = await tx
.select(revisionMetadataColumns)
.from(revisions)
.where(
and(
owner(target, target.entryFile),
cursor && cursorTime
? or(
lt(revisions.createdAt, cursorTime),
and(
eq(revisions.createdAt, cursorTime),
lt(revisions.id, cursor.id),
),
)
: undefined,
),
)
.orderBy(desc(revisions.createdAt), desc(revisions.id))
.limit(limit + 1);
const page = await tx.execute<{ id: string }>(sql`
select id from ${entries}
${target.cursor ? sql`where (created_at, id) < (select created_at, id from ${entries} where id = ${target.cursor})` : sql``}
order by created_at desc, id desc limit ${limit + 1}`);
const ids = Array.from(page, (row) => row.id);
const legacy = ids.length ? await tx.select(revisionMetadataColumns).from(revisions)
.where(and(owner(target, entryFile), inArray(revisions.id, ids))) : [];
const saves = ids.length ? await tx.select().from(activityLog)
.where(and(saveRecords(target, entryFile), inArray(activityLog.id, ids))) : [];
const byId = new Map<string, Omit<Revision, "contentBase64">>([
...legacy.map((row) => [row.id, row] as const),
...saves.map((save) => [save.id, saveRevision(save, entryFile, current)] as const),
]);
const rows = ids.map((id) => byId.get(id)!);
return {
revisions: rows.slice(0, limit).map(metadata),
nextCursor: rows.length > limit ? rows[limit - 1]!.id : null,
};
});
}));
}
async function readRevision(
target: InstructionTarget & { entryFile: string; revisionId: string },
actor: AuthorizationActor,
) {
return db.transaction(async (tx) => {
await lockTarget(tx, target, actor);
return withAgentFilesRestoredBeforeLock(() => db.transaction(async (tx) => {
const state = await lockTarget(tx, target, actor);
await authorizeRead(tx, actor, target);
return snapshot(
await getRevision(
await resolveRevision(
tx,
target,
instructionPath(target.entryFile),
target.revisionId,
await currentFile(tx, target, state),
),
);
});
}));
}
async function diff(
target: InstructionTarget & {
@@ -54,7 +54,7 @@ describe("canonical instruction tools through native authority", () => {
await fs.writeFile(path.join(root, entryFile), original);
});
const call = (tool: string, args: Record<string, unknown> = {}) => authority.execute({ tool, callId: randomUUID(), arguments: { targetAgentId, ...args } }) as Promise<any>;
it("bridges old native instruction tools to current files without writing history", async () => {
it("bridges old native instruction tools to current files and lists the save in history", async () => {
const first = await call("read_agent_instructions");
expect(first).toMatchObject({ entryFile, content: original });
const changed = await call("update_agent_instructions", { entryFile, content: "changed\r\n", baseRevisionId: first.revision.id });
@@ -65,7 +65,9 @@ describe("canonical instruction tools through native authority", () => {
expect(changed.resourceLinks).toEqual([{ kind: "agent", id: targetAgentId, name: "Target",
href: `/${encodeURIComponent(company!.issuePrefix)}/agents/${targetAgentId}` }]);
expect(changed.appliesTo).toMatch(/start after this save/);
expect((await call("get_agent_instruction_history", { entryFile })).revisions).toHaveLength(0);
expect((await call("get_agent_instruction_history", { entryFile })).revisions).toEqual([
expect.objectContaining({ contentHash: changed.revision.contentHash, actorAgentId: agentId, sourceRunId: runId, createdAt: changed.revision.createdAt }),
]);
expect(await fs.readFile(path.join(root, entryFile), "utf8")).toBe("changed\r\n");
await expect(call("update_agent_instructions", { entryFile, content: "stale", baseRevisionId: first.revision.id })).rejects.toMatchObject({ status: 409 });
expect((await call("read_agent_instructions")).content).toBe("changed\r\n");