Skip to content

Commit 4639f85

Browse files
TheGreatAxiosTheGreatAxios
committed
feat(agent-explorer): adopt uniform reusable agent template shape
1 parent b7312c5 commit 4639f85

12 files changed

Lines changed: 222 additions & 88 deletions

File tree

‎agents/explorer/README.md‎

Lines changed: 48 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,48 @@
1+
# @corbits/code-agent-explorer
2+
3+
## What this is
4+
5+
A ready-to-go Corbits agent for the **explorer** role (`@corbits/code-agent-explorer`)
6+
plus its named component parts so a consumer can recreate or remix it. Explorer is
7+
the read-only mapping & search worker: it maps the codebase against the brief and
8+
reports scannable findings — it never implements, reviews, or discovers the fleet.
9+
10+
## Consume (runLocal)
11+
12+
```ts
13+
import { agent } from "@corbits/code-agent-explorer";
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/code-agent-explorer";
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 `READ_TOOLS` surface constant
44+
(`src/agent/directors/tool-sets.ts`) — explorer is deliberately read-only (no
45+
`write_file`/`edit_file`/`delete_file`). The in-tree drift-guard
46+
(`src/agent/directors/explorer/package.test.ts`) enforces they match.
47+
- This package is the single prompt authority for explorer; the in-tree
48+
`src/agent/directors/explorer/package.ts` is deleted.

‎agents/explorer/src/agent.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Explorer 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 explorer 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: "explorer",
20+
systemPrompt: systemPrompt.build(),
21+
tools: [],
22+
capabilities: [],
23+
inference: { sources: [] },
24+
tags: { fleet: "0.3.36", lane: "explorer" },
25+
});
26+
}

‎agents/explorer/src/config.ts‎

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

‎agents/explorer/src/director.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
// Explorer director card — the `DirectorPackage` data, extracted byte-for-byte
2+
// from the in-tree `src/agent/directors/explorer/package.ts` (now deleted).
3+
// Structurally satisfies the app's `DirectorPackage` (asserted in-tree by
4+
// `src/agent/directors/explorer/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 explorer director card. */
11+
export const director = {
12+
id: "explorer",
13+
primaryIntent: "Map and read the codebase; no product edits",
14+
outOfLane: [
15+
"product write paths",
16+
"drive-by fixes",
17+
"shipping features",
18+
"review severity theater",
19+
],
20+
description: "Read-only exploration",
21+
systemPrompt: systemPrompt.build(),
22+
tools: { allow: tools },
23+
spawn: config.spawn,
24+
modelRole: config.modelRole,
25+
tier: config.tier,
26+
} as const;

‎agents/explorer/src/index.ts‎

Lines changed: 9 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -1,74 +1,9 @@
1-
/**
2-
* Explorer worker (CL-7020 / CL-7015 rename from explore).
3-
* Map/read against the brief — scannable findings only; never implement, review, or discover the fleet.
4-
*
5-
* Ships as the @corbits/code-agent-explorer workspace package: the tool allowlist
6-
* lives here so the package stays importable without the app. Drift against
7-
* the app read surface fails src/agent/directors/explorer/package.test.ts.
8-
*/
9-
export type AgentPackage = {
10-
readonly id: "explorer";
11-
readonly primaryIntent: string;
12-
readonly outOfLane: readonly string[];
13-
readonly description: string;
14-
readonly systemPrompt: string;
15-
/** Unset — explorer never attaches skill bodies at spawn. */
16-
readonly attachedSkills?: readonly string[];
17-
/** Unset — explorer 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: "explore";
26-
readonly tier: "leaf";
27-
};
28-
29-
const EXPLORER_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-
] as const;
41-
42-
export const explorerPackage: AgentPackage = {
43-
id: "explorer",
44-
primaryIntent: "Map and read the codebase; no product edits",
45-
outOfLane: [
46-
"product write paths",
47-
"drive-by fixes",
48-
"shipping features",
49-
"review severity theater",
50-
],
51-
description: "Read-only exploration",
52-
systemPrompt: `You are ExplorerDirector (Explorer), a specialist in Corbits Code.
53-
54-
PRIMARY INTENT: map and read the codebase to answer the brief. Read, search, report. Do not implement product changes.
55-
You are the explore lane only — not Coder, not Reviewer, not an orchestrator. Do not spawn specialists. Blinders on: do not discover or enumerate the fleet; stay inside the brief's question.
56-
57-
Map against the brief:
58-
1. Map every success_criteria item to facts you will gather (or Blockers if you cannot).
59-
2. Read and search only what the brief requires — cite paths, symbols, call flow / ownership.
60-
3. Prefer one thorough pass; expand Findings or change approach rather than re-reading the same paths.
61-
4. Report a scannable map, Paths read, and Blockers.
62-
63-
DONE GATE: Stop when every success_criteria item from the brief is answered OR explicitly blocked under Blockers. Do not invent architecture, ship code, or expand the brief after criteria are satisfied. If the ask needs implementation or review, report Blockers — do not become Coder or Reviewer.
64-
65-
FINDINGS SHAPE: Findings must be a scannable map — key paths, symbols, call flow / ownership — not optional prose dump. Cite paths. No drive-by refactors, no feature work, no review severity theater.
66-
67-
FINISH BIAS: Prefer one thorough pass then report. Expand Findings, change approach, or write the final report — do not keep re-reading the same paths.
68-
69-
OUT OF LANE: product writes, drive-by fixes, shipping features, review severity theater, orchestration, spawning specialists, fleet discovery, becoming Coder/Reviewer/orchestrator as primary.`,
70-
tools: { allow: [...EXPLORER_TOOLS] },
71-
spawn: { maySpawn: false },
72-
tier: "leaf",
73-
modelRole: "explore",
74-
};
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/explorer/src/prompt.ts‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
// Explorer card — the single prompt authority, extracted byte-for-byte from the
2+
// in-tree `src/agent/directors/explorer/package.ts` (now deleted). `build()` is
3+
// pure and byte-stable: it returns an identical string on every call.
4+
const CARD = `You are ExplorerDirector (Explorer), a specialist in Corbits Code.
5+
6+
PRIMARY INTENT: map and read the codebase to answer the brief. Read, search, report. Do not implement product changes.
7+
You are the explore lane only — not Coder, not Reviewer, not an orchestrator. Do not spawn specialists. Blinders on: do not discover or enumerate the fleet; stay inside the brief's question.
8+
9+
Map against the brief:
10+
1. Map every success_criteria item to facts you will gather (or Blockers if you cannot).
11+
2. Read and search only what the brief requires — cite paths, symbols, call flow / ownership.
12+
3. Prefer one thorough pass; expand Findings or change approach rather than re-reading the same paths.
13+
4. Report a scannable map, Paths read, and Blockers.
14+
15+
DONE GATE: Stop when every success_criteria item from the brief is answered OR explicitly blocked under Blockers. Do not invent architecture, ship code, or expand the brief after criteria are satisfied. If the ask needs implementation or review, report Blockers — do not become Coder or Reviewer.
16+
17+
FINDINGS SHAPE: Findings must be a scannable map — key paths, symbols, call flow / ownership — not optional prose dump. Cite paths. No drive-by refactors, no feature work, no review severity theater.
18+
19+
FINISH BIAS: Prefer one thorough pass then report. Expand Findings, change approach, or write the final report — do not keep re-reading the same paths.
20+
21+
OUT OF LANE: product writes, drive-by fixes, shipping features, review severity theater, orchestration, spawning specialists, fleet discovery, becoming Coder/Reviewer/orchestrator as primary.`;
22+
23+
/** Stable identifier of the package's voice. */
24+
export const theme = "explorer";
25+
26+
/** Byte-stable builder: returns the raw explorer card, identical every call. */
27+
export const systemPrompt = {
28+
theme,
29+
build: (): string => CARD,
30+
};

‎agents/explorer/src/toolset.ts‎

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

‎agents/explorer/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: 0 additions & 1 deletion
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎package.json‎

Lines changed: 0 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -86,7 +86,6 @@
8686
"tar": "^7.5.1"
8787
},
8888
"dependencies": {
89-
"@corbits/code-agent-explorer": "workspace:*",
9089
"@corbits/codex-provider": "0.1.1",
9190
"@corbits/oauth-core": "0.2.0",
9291
"@corbits/openai-responses": "0.2.1",

0 commit comments

Comments
 (0)