Skip to content

Commit 3667f9e

Browse files
TheGreatAxiosTheGreatAxios
committed
feat(agent-warden): adopt uniform reusable agent template shape
1 parent 3bc802c commit 3667f9e

14 files changed

Lines changed: 227 additions & 106 deletions

File tree

‎agents/warden/README.md‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
# @corbits/agent-warden
2+
3+
## What this is
4+
5+
A ready-to-go Corbits agent for the **warden** role (`@corbits/agent-warden`)
6+
plus its named component parts so a consumer can recreate or remix it. Warden is
7+
the trust-review worker: it reviews permission, provider-auth, and plugin-loader
8+
diffs only, and never fixes product code.
9+
10+
## Consume (runLocal)
11+
12+
```ts
13+
import { agent } from "@corbits/agent-warden";
14+
const run = runLocal(defining(agent), env);
15+
```
16+
17+
## Consume (deploy runWorkflow / hub / sidecar)
18+
19+
Hand the same `AgentDefinition` (`agent`) to a workflow, hub, or sidecar. The
20+
package never exports a workflow itself — a workflow _consumes_ `agent`.
21+
22+
## Remix components
23+
24+
```ts
25+
import {
26+
director,
27+
tools,
28+
systemPrompt,
29+
config,
30+
defineAgent,
31+
} from "@corbits/agent-warden";
32+
33+
// Swap components at the consumer side.
34+
defineAgent({ director, tools, systemPrompt, config }); // or spread overrides
35+
```
36+
37+
Each of `agent`, `defineAgent`, `director`, `tools`, `systemPrompt`, `config` is a
38+
named, independently importable part.
39+
40+
## Byte-stability & single authority
41+
42+
- `systemPrompt.build()` is pure and byte-stable — identical string every call.
43+
- `tools` is the literal expansion of the app's `REVIEW_TOOLS` surface constant
44+
(`src/agent/directors/tool-sets.ts`); the in-tree drift-guard
45+
(`src/agent/directors/warden/package.test.ts`) enforces they match.
46+
- This package is the single prompt authority for warden; the in-tree
47+
`src/agent/directors/warden/package.ts` is deleted.

‎agents/warden/package.json‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
{
2-
"name": "@corbits/code-agent-warden",
2+
"name": "@corbits/agent-warden",
33
"version": "0.1.0",
44
"private": true,
55
"type": "module",

‎agents/warden/src/agent.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Warden assembled agent — ready unit + package defineAgent wrapper.
2+
// Calls `@intx/agent`'s `defineAgent` directly (no Corbits bridge/helper layer).
3+
// Tool mounting is consumer/app-side: `tools` here is [] (the allowlist surface
4+
// is exported from `./toolset.js` and wired by the app harness).
5+
6+
import {
7+
defineAgent as coreDefineAgent,
8+
type AgentDefinition,
9+
} from "@intx/agent";
10+
11+
import { systemPrompt } from "./prompt.js";
12+
13+
/** The assembled warden agent — ready to hand to `runLocal` / `runWorkflow`. */
14+
export const agent: AgentDefinition = defineAgent();
15+
16+
/** Package convenience wrapper → `AgentDefinition` for `runLocal` authoring. */
17+
export function defineAgent(): AgentDefinition {
18+
return coreDefineAgent({
19+
id: "warden",
20+
systemPrompt: systemPrompt.build(),
21+
tools: [],
22+
capabilities: [],
23+
inference: { sources: [] },
24+
tags: { fleet: "0.3.36", lane: "warden" },
25+
});
26+
}

‎agents/warden/src/config.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
// Warden config — uniform `{ spawn, tier, modelRole }` shape (§5).
2+
// warden is a leaf trust-review worker: maySpawn false, no allowlist.
3+
export const config = {
4+
spawn: {
5+
maySpawn: false,
6+
},
7+
tier: "leaf",
8+
modelRole: "review",
9+
} as const satisfies {
10+
spawn: { maySpawn: boolean; allowlist?: readonly string[] };
11+
tier: string;
12+
modelRole: string;
13+
};

‎agents/warden/src/director.ts‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
// Warden director card — the `DirectorPackage` data, extracted byte-for-byte
2+
// from the in-tree `src/agent/directors/warden/package.ts` (now deleted).
3+
// Structurally satisfies the app's `DirectorPackage` (asserted in-tree by
4+
// `src/agent/directors/warden/package.test.ts`); it imports @intx/* only.
5+
6+
import { tools } from "./toolset.js";
7+
import { systemPrompt } from "./prompt.js";
8+
import { config } from "./config.js";
9+
10+
/** The assembled warden director card. */
11+
export const director = {
12+
id: "warden",
13+
primaryIntent:
14+
"Trust review of permission, provider-auth, and plugin-loader diffs; never fix product code",
15+
outOfLane: [
16+
"implementing fixes",
17+
"general code review outside trust paths",
18+
"architecture judgment without trust evidence",
19+
"feature design",
20+
],
21+
description: "Permission and trust review worker",
22+
systemPrompt: systemPrompt.build(),
23+
tools: { allow: tools },
24+
spawn: config.spawn,
25+
modelRole: config.modelRole,
26+
tier: config.tier,
27+
} as const;

‎agents/warden/src/index.ts‎

Lines changed: 9 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,9 @@
1-
/**
2-
* Warden trust-review worker (CL-7657).
3-
* Permission / provider-auth / plugin-loader diffs only; findings, never fixes.
4-
*
5-
* Ships as the @corbits/code-agent-warden workspace package: the tool allowlist
6-
* lives here so the package stays importable without the app. Drift against
7-
* the app build surface fails src/agent/directors/warden/package.test.ts.
8-
*/
9-
export type AgentPackage = {
10-
readonly id: "warden";
11-
readonly primaryIntent: string;
12-
readonly outOfLane: readonly string[];
13-
readonly description: string;
14-
readonly systemPrompt: string;
15-
/** Unset — warden never attaches skill bodies at spawn. */
16-
readonly attachedSkills?: readonly string[];
17-
/** Unset — warden declares no skill scope. */
18-
readonly optionalSkills?: readonly string[];
19-
readonly tools: {
20-
readonly allow: readonly string[];
21-
};
22-
readonly spawn: {
23-
readonly maySpawn: false;
24-
};
25-
readonly modelRole: "review";
26-
readonly tier: "leaf";
27-
};
28-
29-
const WARDEN_TOOLS = [
30-
"read_file",
31-
"grep",
32-
"search_files",
33-
"list_dir",
34-
"lsp",
35-
"run_shell",
36-
"web_fetch",
37-
"web_search",
38-
"skill_search",
39-
"use_skill",
40-
"write_file",
41-
"edit_file",
42-
"delete_file",
43-
] as const;
44-
45-
export const wardenPackage: AgentPackage = {
46-
id: "warden",
47-
primaryIntent:
48-
"Trust review of permission, provider-auth, and plugin-loader diffs; never fix product code",
49-
outOfLane: [
50-
"implementing fixes",
51-
"general code review outside trust paths",
52-
"architecture judgment without trust evidence",
53-
"feature design",
54-
],
55-
description: "Permission and trust review worker",
56-
systemPrompt: `You are WardenDirector (Warden), a specialist in Corbits Code.
57-
58-
PRIMARY INTENT: trust review of permission, provider-auth, and plugin-loader diffs. Find trust defects with evidence; never fix product code. Cite path, line or symbol, what breaks, and the concrete input or sequence that triggers it.
59-
60-
TRIGGER — written paths only. Review only when the diff touches permission, provider-auth, or plugin-loader code. Anything else is out of lane: say so under Blockers and stop. Do not expand into general code review.
61-
62-
You are the trust lane only — not an implementer, not an explorer, not an orchestrator. Do not ship fixes. Do not become Reviewer (general defects) or Planner as your primary job.
63-
64-
Findings lens — rank each as blocking, should-fix, or file-for-later:
65-
- grant-matching holes (permission grants that over- or under-match the request)
66-
- secret-guard bypass (secrets or credentials reachable past the guard)
67-
- arktype boundary skips (unvalidated input crossing a trust boundary)
68-
- shell-policy peel gaps (shell policy peeled or bypassed by a wrapper layer)
69-
- plugin trust (untrusted plugin code gaining capability it was not granted)
70-
71-
Evidence rules:
72-
- Every claim needs path + line/symbol + reproduction shape (input, sequence, missing branch).
73-
- "This is genuinely fine" is a valid finding when true.
74-
- Call out gaps: what you did not cover so the parent does not assume closed.
75-
- Recommend permanent regression tests that Coder should land.
76-
77-
OUT OF LANE → refuse or reclassify under Blockers:
78-
- implementing fixes (route to coder)
79-
- general code review outside trust paths (route to reviewer)
80-
- feature requirements or planning (route to planner)`,
81-
tools: { allow: [...WARDEN_TOOLS] },
82-
spawn: { maySpawn: false },
83-
tier: "leaf",
84-
modelRole: "review",
85-
};
1+
// Public surface — re-exports only (no logic). Exports exactly
2+
// `agent, defineAgent, director, tools, systemPrompt, config`. No `workflow`
3+
// export. No Corbits shared package is re-exported; the package's `director`
4+
// structurally satisfies the app's `DirectorPackage` (app-side drift-guard).
5+
export { agent, defineAgent } from "./agent.js";
6+
export { director } from "./director.js";
7+
export { tools } from "./toolset.js";
8+
export { systemPrompt } from "./prompt.js";
9+
export { config } from "./config.js";

‎agents/warden/src/prompt.ts‎

Lines changed: 37 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,37 @@
1+
// Warden card — the single prompt authority, extracted byte-for-byte from the
2+
// in-tree `src/agent/directors/warden/package.ts` (now deleted). `build()` is
3+
// pure and byte-stable: it returns an identical string on every call.
4+
const CARD = `You are WardenDirector (Warden), a specialist in Corbits Code.
5+
6+
PRIMARY INTENT: trust review of permission, provider-auth, and plugin-loader diffs. Find trust defects with evidence; never fix product code. Cite path, line or symbol, what breaks, and the concrete input or sequence that triggers it.
7+
8+
TRIGGER — written paths only. Review only when the diff touches permission, provider-auth, or plugin-loader code. Anything else is out of lane: say so under Blockers and stop. Do not expand into general code review.
9+
10+
You are the trust lane only — not an implementer, not an explorer, not an orchestrator. Do not ship fixes. Do not become Reviewer (general defects) or Planner as your primary job.
11+
12+
Findings lens — rank each as blocking, should-fix, or file-for-later:
13+
- grant-matching holes (permission grants that over- or under-match the request)
14+
- secret-guard bypass (secrets or credentials reachable past the guard)
15+
- arktype boundary skips (unvalidated input crossing a trust boundary)
16+
- shell-policy peel gaps (shell policy peeled or bypassed by a wrapper layer)
17+
- plugin trust (untrusted plugin code gaining capability it was not granted)
18+
19+
Evidence rules:
20+
- Every claim needs path + line/symbol + reproduction shape (input, sequence, missing branch).
21+
- "This is genuinely fine" is a valid finding when true.
22+
- Call out gaps: what you did not cover so the parent does not assume closed.
23+
- Recommend permanent regression tests that Coder should land.
24+
25+
OUT OF LANE → refuse or reclassify under Blockers:
26+
- implementing fixes (route to coder)
27+
- general code review outside trust paths (route to reviewer)
28+
- feature requirements or planning (route to planner)`;
29+
30+
/** Stable identifier of the package's voice. */
31+
export const theme = "warden";
32+
33+
/** Byte-stable builder: returns the raw warden card, identical every call. */
34+
export const systemPrompt = {
35+
theme,
36+
build: (): string => CARD,
37+
};

‎agents/warden/src/toolset.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Warden trust-review: review surface (read + product writes) — REVIEW_TOOLS.
2+
// Literal expansion of the `REVIEW_TOOLS` constant in
3+
// `src/agent/directors/tool-sets.ts` (the single tool authority). Drift is
4+
// enforced by the in-tree `src/agent/directors/warden/package.test.ts`.
5+
const REVIEW_TOOLS = [
6+
"read_file",
7+
"grep",
8+
"search_files",
9+
"list_dir",
10+
"lsp",
11+
"run_shell",
12+
"web_fetch",
13+
"web_search",
14+
"skill_search",
15+
"use_skill",
16+
"write_file",
17+
"edit_file",
18+
"delete_file",
19+
] as const;
20+
21+
/** The warden tool allowlist — literal equal to the in-tree `REVIEW_TOOLS`. */
22+
export const tools: readonly string[] = [...REVIEW_TOOLS];

‎agents/warden/tsconfig.json‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
{
2+
"extends": "../../tsconfig.base.json",
3+
"compilerOptions": {
4+
"noEmit": true
5+
},
6+
"include": ["src/**/*.ts"]
7+
}

‎bun.lock‎

Lines changed: 2 additions & 3 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

0 commit comments

Comments
 (0)