Skip to content

Commit e2edee3

Browse files
TheGreatAxiosTheGreatAxios
committed
feat(explorer): ship explorer as a workspace agent package
1 parent d22b8e3 commit e2edee3

14 files changed

Lines changed: 218 additions & 26 deletions

File tree

‎agents/explorer/README.md‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,38 @@
1+
# @corbits/code-agent-explorer
2+
3+
## What this is
4+
5+
Ready `@corbits/code-agent-explorer` agent + independently importable components:
6+
`agent`, `defineAgent`, `director`, `tools`, `systemPrompt`, `config`. 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` to a workflow — the package never exports a
20+
workflow itself.
21+
22+
## Remix components
23+
24+
```ts
25+
import { director, tools, systemPrompt, config } from "@corbits/code-agent-explorer";
26+
defineAgent({ director, ... }); // or swap tools / systemPrompt / config
27+
```
28+
29+
Each of `agent`, `defineAgent`, `director`, `tools`, `systemPrompt`, `config` is a
30+
named, independently importable part.
31+
32+
## Single authority
33+
34+
`prompt.ts` `systemPrompt.build()` is byte-stable (the raw card, no formatting).
35+
`toolset.ts` `tools` literal equals the `READ_TOOLS` surface constant in
36+
`src/agent/directors/tool-sets.ts` (explorer is deliberately read-only — no
37+
`write_file`/`edit_file`/`delete_file`); drift is enforced by the in-tree
38+
drift-guard `src/agent/directors/explorer/package.test.ts`.

‎agents/explorer/package.json‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
{
2+
"name": "@corbits/code-agent-explorer",
3+
"version": "0.1.0",
4+
"private": true,
5+
"type": "module",
6+
"license": "SEE LICENSE IN LICENSE.md",
7+
"exports": {
8+
".": {
9+
"types": "./src/index.ts",
10+
"default": "./src/index.ts"
11+
}
12+
}
13+
}

‎agents/explorer/src/agent.ts‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
// Explorer assembled agent — ready unit + package defineAgent wrapper. Calls
2+
// `@intx/agent`'s `defineAgent` directly (no Corbits bridge). Tool mounting is
3+
// consumer/app-side: `tools` here is [] (the allowlist surface is exported from
4+
// `./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+
export const agent: AgentDefinition = defineAgent();
14+
15+
export function defineAgent(): AgentDefinition {
16+
return coreDefineAgent({
17+
id: "explorer",
18+
systemPrompt: systemPrompt.build(),
19+
tools: [],
20+
capabilities: [],
21+
inference: { sources: [] },
22+
});
23+
}

‎agents/explorer/src/config.ts‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
export const config = {
2+
spawn: { maySpawn: false },
3+
tier: "leaf",
4+
modelRole: "explore",
5+
} as const satisfies {
6+
spawn: { maySpawn: boolean; allowlist?: readonly string[] };
7+
tier: string;
8+
modelRole: string;
9+
};

‎agents/explorer/src/director.ts‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
// Explorer director card; imports @intx/* only. The app asserts this satisfies
2+
// `DirectorPackage` in-tree (src/agent/directors/explorer/package.test.ts).
3+
import { tools } from "./toolset.js";
4+
import { systemPrompt } from "./prompt.js";
5+
import { config } from "./config.js";
6+
7+
export const director = {
8+
id: "explorer",
9+
primaryIntent: "Map and read the codebase; no product edits",
10+
outOfLane: [
11+
"product write paths",
12+
"drive-by fixes",
13+
"shipping features",
14+
"review severity theater",
15+
],
16+
description: "Read-only exploration",
17+
systemPrompt: systemPrompt.build(),
18+
tools: { allow: tools },
19+
spawn: config.spawn,
20+
modelRole: config.modelRole,
21+
tier: config.tier,
22+
} as const;

‎agents/explorer/src/index.ts‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
// Public surface — re-exports only, so the package imports no Corbits code
2+
// (the app asserts the director contract in-tree via drift-guard). No `workflow`
3+
// export: workflows consume `agent`.
4+
export { agent, defineAgent } from "./agent.js";
5+
export { director } from "./director.js";
6+
export { tools } from "./toolset.js";
7+
export { systemPrompt } from "./prompt.js";
8+
export { config } from "./config.js";

src/agent/directors/explorer/package.ts renamed to agents/explorer/src/prompt.ts

Lines changed: 12 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,6 @@
1-
import type { DirectorPackage } from "../types.js";
2-
import { READ_TOOLS } from "../tool-sets.js";
3-
4-
/**
5-
* Explorer worker (CL-7020 / CL-7015 rename from explore).
6-
* Map/read against the brief — scannable findings only; never implement, review, or discover the fleet.
7-
*/
8-
export const explorerPackage: DirectorPackage = {
9-
id: "explorer",
10-
primaryIntent: "Map and read the codebase; no product edits",
11-
outOfLane: [
12-
"product write paths",
13-
"drive-by fixes",
14-
"shipping features",
15-
"review severity theater",
16-
],
17-
description: "Read-only exploration",
18-
systemPrompt: `You are ExplorerDirector (Explorer), a specialist in Corbits Code.
1+
// Single prompt authority: `build()` is pure and byte-stable — it returns an
2+
// identical string on every call.
3+
const CARD = `You are ExplorerDirector (Explorer), a specialist in Corbits Code.
194
205
PRIMARY INTENT: map and read the codebase to answer the brief. Read, search, report. Do not implement product changes.
216
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.
@@ -30,9 +15,13 @@ DONE GATE: Stop when every success_criteria item from the brief is answered OR e
3015
3116
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.
3217
33-
OUT OF LANE: product writes, drive-by fixes, shipping features, review severity theater, orchestration, spawning specialists, fleet discovery, becoming Coder/Reviewer/orchestrator as primary.`,
34-
tools: { allow: READ_TOOLS },
35-
spawn: { maySpawn: false },
36-
tier: "leaf",
37-
modelRole: "explore",
18+
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.
19+
20+
OUT OF LANE: product writes, drive-by fixes, shipping features, review severity theater, orchestration, spawning specialists, fleet discovery, becoming Coder/Reviewer/orchestrator as primary.`;
21+
22+
export const theme = "explorer";
23+
24+
export const systemPrompt = {
25+
theme,
26+
build: (): string => CARD,
3827
};

‎agents/explorer/src/toolset.ts‎

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

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

0 commit comments

Comments
 (0)