Skip to content

Commit 409ef90

Browse files
feat(agents): add project custom agents
Add Markdown-defined agents, project defaults, composer selection, and named T3 delegation with model preferences and instruction delivery.
1 parent ed0f7b9 commit 409ef90

49 files changed

Lines changed: 2749 additions & 89 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.
Lines changed: 310 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,310 @@
1+
import * as NodeServices from "@effect/platform-node/NodeServices";
2+
import { assert, describe, it } from "@effect/vitest";
3+
import {
4+
AgentDefinition,
5+
AgentId,
6+
ProviderDriverKind,
7+
ProviderInstanceId,
8+
type ServerProvider,
9+
} from "@t3tools/contracts";
10+
import * as Effect from "effect/Effect";
11+
import * as FileSystem from "effect/FileSystem";
12+
import * as Option from "effect/Option";
13+
import * as Path from "effect/Path";
14+
import * as Schema from "effect/Schema";
15+
16+
import { getAgentDefinition, listAgentSummaries, resolveModelForAgent } from "./AgentService.ts";
17+
18+
/** An agent file: frontmatter lines, then the body that becomes its instructions. */
19+
const agentFile = (frontmatter: ReadonlyArray<string>, body: string) =>
20+
["---", ...frontmatter, "---", "", body].join("\n");
21+
22+
const writeFiles = Effect.fn("writeFiles")(function* (root: string, files: Record<string, string>) {
23+
const fs = yield* FileSystem.FileSystem;
24+
const path = yield* Path.Path;
25+
for (const [relativePath, contents] of Object.entries(files)) {
26+
const filePath = path.join(root, relativePath);
27+
yield* fs.makeDirectory(path.dirname(filePath), { recursive: true });
28+
yield* fs.writeFileString(filePath, contents);
29+
}
30+
});
31+
32+
const decodeAgentDefinition = Schema.decodeUnknownSync(AgentDefinition);
33+
34+
const definition = (fields: Record<string, unknown>) =>
35+
decodeAgentDefinition({
36+
id: "reviewer",
37+
name: "Reviewer",
38+
description: "Reviews diffs.",
39+
instructions: "Review the diff.",
40+
...fields,
41+
});
42+
43+
const provider = (
44+
instanceId: string,
45+
driver: string,
46+
slugs: ReadonlyArray<string>,
47+
): ServerProvider => ({
48+
instanceId: ProviderInstanceId.make(instanceId),
49+
driver: ProviderDriverKind.make(driver),
50+
enabled: true,
51+
installed: true,
52+
version: "test",
53+
status: "ready",
54+
auth: { status: "authenticated" },
55+
checkedAt: "2026-10-10T00:00:00.000Z",
56+
models: slugs.map((slug) => ({ slug, name: slug, isCustom: false, capabilities: null })),
57+
slashCommands: [],
58+
skills: [],
59+
});
60+
61+
it.layer(NodeServices.layer)("agent discovery", (it) => {
62+
it.effect("discovers agents from every agent location and AGENTS.md", () =>
63+
Effect.gen(function* () {
64+
const fs = yield* FileSystem.FileSystem;
65+
const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agents-locations-" });
66+
yield* writeFiles(root, {
67+
".agents/planner.agent.md": agentFile(
68+
["id: planner", "name: Planner", "description: Plans work."],
69+
"Plan it.",
70+
),
71+
".agents/reviewer.md": agentFile(
72+
["id: reviewer", "name: Reviewer", "description: Reviews work."],
73+
"Review it.",
74+
),
75+
".github/agents/tester.agent.md": agentFile(
76+
["id: tester", "name: Tester", "description: Tests work."],
77+
"Test it.",
78+
),
79+
".github/agents/docs.md": agentFile(
80+
["id: docs", "name: Docs", "description: Writes docs."],
81+
"Document it.",
82+
),
83+
"AGENTS.md": agentFile(
84+
["id: coordinator", "name: Coordinator", "description: Coordinates work."],
85+
"Coordinate it.",
86+
),
87+
});
88+
89+
const agents = yield* listAgentSummaries(root);
90+
91+
assert.deepEqual(agents.map((agent) => agent.id).toSorted(), [
92+
"coordinator",
93+
"docs",
94+
"planner",
95+
"reviewer",
96+
"tester",
97+
]);
98+
}),
99+
);
100+
101+
it.effect("parses every frontmatter field and keeps the body as instructions", () =>
102+
Effect.gen(function* () {
103+
const fs = yield* FileSystem.FileSystem;
104+
const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agents-fields-" });
105+
yield* writeFiles(root, {
106+
".agents/full.agent.md": agentFile(
107+
[
108+
"id: full",
109+
"name: Full agent",
110+
"description: Uses every field.",
111+
"model:",
112+
" provider: claudeAgent",
113+
" model: claude-haiku-4-5",
114+
"tier: economy",
115+
"tools:",
116+
" allow: [read, search]",
117+
" deny: [shell]",
118+
"canDelegateTo: [planner]",
119+
],
120+
"Be exhaustive.\n\nKeep it short.",
121+
),
122+
});
123+
124+
const agent = Option.getOrUndefined(yield* getAgentDefinition(AgentId.make("full"), root));
125+
126+
assert.deepEqual(agent, {
127+
id: AgentId.make("full"),
128+
name: "Full agent",
129+
description: "Uses every field.",
130+
model: { instanceId: ProviderInstanceId.make("claudeAgent"), model: "claude-haiku-4-5" },
131+
tier: "economy",
132+
canDelegateTo: [AgentId.make("planner")],
133+
instructions: "Be exhaustive.\n\nKeep it short.",
134+
});
135+
assert.deepEqual(yield* listAgentSummaries(root), [
136+
{
137+
id: AgentId.make("full"),
138+
name: "Full agent",
139+
description: "Uses every field.",
140+
tier: "economy",
141+
model: { instanceId: ProviderInstanceId.make("claudeAgent"), model: "claude-haiku-4-5" },
142+
},
143+
]);
144+
}),
145+
);
146+
147+
it.effect("leaves the tier unset and defaults delegation to empty", () =>
148+
Effect.gen(function* () {
149+
const fs = yield* FileSystem.FileSystem;
150+
const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agents-defaults-" });
151+
yield* writeFiles(root, {
152+
".github/agents/minimal.agent.md": agentFile(
153+
["id: minimal", "name: Minimal", "description: Bare minimum."],
154+
"Do the task.",
155+
),
156+
});
157+
158+
const agent = Option.getOrUndefined(yield* getAgentDefinition(AgentId.make("minimal"), root));
159+
160+
assert.deepEqual(agent, {
161+
id: AgentId.make("minimal"),
162+
name: "Minimal",
163+
description: "Bare minimum.",
164+
canDelegateTo: [],
165+
instructions: "Do the task.",
166+
});
167+
}),
168+
);
169+
170+
it.effect("skips guidance and invalid definitions without hiding valid agents", () =>
171+
Effect.gen(function* () {
172+
const fs = yield* FileSystem.FileSystem;
173+
const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agents-invalid-" });
174+
yield* writeFiles(root, {
175+
"AGENTS.md": "# Project guidance\n\nNo frontmatter here.",
176+
".agents/notes.md": "Just notes.",
177+
".agents/bad-id.agent.md": agentFile(
178+
["id: Bad Id", "name: Bad id", "description: Not kebab case."],
179+
"Body.",
180+
),
181+
".agents/bad-tier.agent.md": agentFile(
182+
["id: bad-tier", "name: Bad tier", "description: Unknown tier.", "tier: fast"],
183+
"Body.",
184+
),
185+
".agents/empty-body.agent.md": agentFile(
186+
["id: empty-body", "name: Empty body", "description: No instructions."],
187+
"",
188+
),
189+
".agents/broken.agent.md": "---\nid: [unclosed\n---\n\nBody.",
190+
".agents/valid.agent.md": agentFile(
191+
["id: valid", "name: Valid", "description: Parses fine."],
192+
"Body.",
193+
),
194+
});
195+
196+
const agents = yield* listAgentSummaries(root);
197+
198+
assert.deepEqual(
199+
agents.map((agent) => agent.id),
200+
["valid"],
201+
);
202+
}),
203+
);
204+
205+
it.effect("keeps the first definition when two locations define the same id", () =>
206+
Effect.gen(function* () {
207+
const fs = yield* FileSystem.FileSystem;
208+
const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agents-duplicate-" });
209+
yield* writeFiles(root, {
210+
".agents/reviewer.agent.md": agentFile(
211+
["id: reviewer", "name: Local reviewer", "description: Local copy."],
212+
"Local.",
213+
),
214+
"AGENTS.md": agentFile(
215+
["id: reviewer", "name: Root reviewer", "description: Root copy."],
216+
"Root.",
217+
),
218+
});
219+
220+
const agent = Option.getOrUndefined(
221+
yield* getAgentDefinition(AgentId.make("reviewer"), root),
222+
);
223+
224+
assert.equal(agent?.name, "Local reviewer");
225+
assert.lengthOf(yield* listAgentSummaries(root), 1);
226+
}),
227+
);
228+
229+
it.effect("finds nothing without a workspace root, in an empty one, or for an unknown id", () =>
230+
Effect.gen(function* () {
231+
const fs = yield* FileSystem.FileSystem;
232+
const root = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agents-none-" });
233+
const emptyRoot = yield* fs.makeTempDirectoryScoped({ prefix: "t3-agents-empty-" });
234+
yield* writeFiles(root, {
235+
".agents/reviewer.agent.md": agentFile(
236+
["id: reviewer", "name: Reviewer", "description: Reviews."],
237+
"Review.",
238+
),
239+
});
240+
241+
assert.deepEqual(yield* listAgentSummaries(null), []);
242+
assert.deepEqual(yield* listAgentSummaries(emptyRoot), []);
243+
assert.isTrue(Option.isNone(yield* getAgentDefinition(AgentId.make("reviewer"), null)));
244+
assert.isTrue(Option.isNone(yield* getAgentDefinition(AgentId.make("missing"), root)));
245+
}),
246+
);
247+
});
248+
249+
describe("resolveModelForAgent", () => {
250+
const claude = provider("claudeAgent", "claudeAgent", ["claude-fable-5-1", "claude-haiku-4-5"]);
251+
const codex = provider("codex", "codex", ["gpt-5.4"]);
252+
253+
it("prefers an explicit model in the agent file over its tier", () => {
254+
const agent = definition({ tier: "economy", model: { provider: "codex", model: "gpt-5.4" } });
255+
256+
assert.deepEqual(resolveModelForAgent(agent, [claude, codex]), {
257+
instanceId: ProviderInstanceId.make("codex"),
258+
model: "gpt-5.4",
259+
});
260+
});
261+
262+
it("maps an explicit tier to the driver's available default model", () => {
263+
assert.deepEqual(resolveModelForAgent(definition({ tier: "economy" }), [claude]), {
264+
instanceId: ProviderInstanceId.make("claudeAgent"),
265+
model: "claude-haiku-4-5",
266+
});
267+
assert.deepEqual(resolveModelForAgent(definition({ tier: "reasoning" }), [claude]), {
268+
instanceId: ProviderInstanceId.make("claudeAgent"),
269+
model: "claude-fable-5-1",
270+
});
271+
assert.isUndefined(resolveModelForAgent(definition({}), [claude]));
272+
});
273+
274+
it("picks from the first provider that advertises the tier model", () => {
275+
assert.deepEqual(resolveModelForAgent(definition({ tier: "economy" }), [codex, claude]), {
276+
instanceId: ProviderInstanceId.make("claudeAgent"),
277+
model: "claude-haiku-4-5",
278+
});
279+
});
280+
281+
it("returns nothing when no provider advertises the tier model", () => {
282+
assert.isUndefined(resolveModelForAgent(definition({ tier: "economy" }), [codex]));
283+
});
284+
285+
it("prefers the current provider instance when it offers the tier model", () => {
286+
const firstClaude = provider("claude-first", "claudeAgent", ["claude-haiku-4-5"]);
287+
const currentClaude = provider("claude-current", "claudeAgent", ["claude-haiku-4-5"]);
288+
289+
assert.deepEqual(
290+
resolveModelForAgent(
291+
definition({ tier: "economy" }),
292+
[firstClaude, currentClaude],
293+
currentClaude.instanceId,
294+
),
295+
{ instanceId: currentClaude.instanceId, model: "claude-haiku-4-5" },
296+
);
297+
});
298+
299+
it("skips providers that are disabled, unavailable, or missing the fixed model", () => {
300+
const disabled = { ...codex, enabled: false };
301+
const unavailable = { ...claude, availability: "unavailable" as const };
302+
assert.isUndefined(
303+
resolveModelForAgent(
304+
definition({ model: { instanceId: codex.instanceId, model: "gpt-5.4" } }),
305+
[disabled],
306+
),
307+
);
308+
assert.isUndefined(resolveModelForAgent(definition({ tier: "economy" }), [unavailable]));
309+
});
310+
});

0 commit comments

Comments
 (0)