Skip to content

Commit 6e07498

Browse files
TheGreatAxiosTheGreatAxios
committed
feat(agent-prober): adopt uniform reusable agent template shape
1 parent 26339c1 commit 6e07498

14 files changed

Lines changed: 232 additions & 133 deletions

File tree

‎agents/prober/README.md‎

Lines changed: 35 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,35 @@
1+
# @corbits/agent-prober
2+
3+
## What this is
4+
5+
Ready `@corbits/agent-prober` agent + independently importable components:
6+
`agent`, `defineAgent`, `director`, `tools`, `systemPrompt`, `config`.
7+
8+
## Consume (runLocal)
9+
10+
```ts
11+
import { agent } from "@corbits/agent-prober";
12+
const run = runLocal(defining(agent), env);
13+
```
14+
15+
## Consume (deploy runWorkflow / hub / sidecar)
16+
17+
Hand the same `AgentDefinition` to a workflow — the package never exports a
18+
workflow itself.
19+
20+
## Remix components
21+
22+
```ts
23+
import { director, tools, systemPrompt, config } from "@corbits/agent-prober";
24+
defineAgent({ director, ... }); // or swap tools / systemPrompt / config
25+
```
26+
27+
Each of `director`, `tools`, `systemPrompt`, and `config` is a named,
28+
independently importable part.
29+
30+
## Single authority
31+
32+
`prompt.ts` `systemPrompt.build()` is byte-stable (the raw card, no formatting).
33+
`toolset.ts` `tools` literal equals the `REVIEW_TOOLS` surface constant in
34+
`src/agent/directors/tool-sets.ts`; drift is enforced by the in-tree drift-guard
35+
`src/agent/directors/prober/package.test.ts`.

‎agents/prober/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-prober",
2+
"name": "@corbits/agent-prober",
33
"version": "0.1.0",
44
"private": true,
55
"type": "module",

‎agents/prober/src/agent.ts‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
import {
2+
defineAgent as coreDefineAgent,
3+
type AgentDefinition,
4+
} from "@intx/agent";
5+
import { systemPrompt } from "./prompt.js";
6+
7+
/**
8+
* Prober ready agent — `agent = defineAgent()` plus the named component parts
9+
* (director/tools/systemPrompt/config) form the whole package surface.
10+
*/
11+
export const agent: AgentDefinition = defineAgent();
12+
13+
export function defineAgent(): AgentDefinition {
14+
return coreDefineAgent({
15+
id: "prober",
16+
systemPrompt: systemPrompt.build(),
17+
tools: [], // tool mounting is consumer/app-side; surface enforced by drift-guard
18+
capabilities: [],
19+
inference: {
20+
sources: [{ provider: "openai", model: "gpt-5" }],
21+
},
22+
tags: { fleet: "0.3.36", lane: "prober" },
23+
});
24+
}

‎agents/prober/src/config.ts‎

Lines changed: 13 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,13 @@
1+
/** Prober worker — measure-only latency/behavior prober per family/model. */
2+
export const config = {
3+
spawn: { maySpawn: false },
4+
tier: "leaf",
5+
// Preserved from the original in-tree card (behavior wins over the contract
6+
// §5 map; test defaults to medium effort in identity.ts, matching the
7+
// measure-only lane).
8+
modelRole: "test",
9+
} as const satisfies {
10+
spawn: { maySpawn: boolean };
11+
tier: string;
12+
modelRole: string;
13+
};

‎agents/prober/src/director.ts‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
import { tools } from "./toolset.js";
2+
import { systemPrompt } from "./prompt.js";
3+
import { config } from "./config.js";
4+
5+
/**
6+
* Prober worker director card (CL-7656). Structurally satisfies the app's
7+
* `DirectorPackage` (app-side drift-guard asserts assignability). App-independent.
8+
*/
9+
export const director = {
10+
id: "prober",
11+
primaryIntent:
12+
"Measure latency and behavior distributions per family/model; never ship product code, never tune prompts or policy",
13+
outOfLane: [
14+
"shipping product code",
15+
"tuning prompts or model-family policy",
16+
"building a new eval harness",
17+
"fleet orchestration",
18+
"architecture essays without measurements",
19+
],
20+
description: "Measure-only latency/behavior prober per family/model",
21+
systemPrompt: systemPrompt.build(),
22+
tools: { allow: [...tools] },
23+
spawn: config.spawn,
24+
tier: config.tier,
25+
modelRole: config.modelRole,
26+
} as const;

‎agents/prober/src/index.ts‎

Lines changed: 8 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -1,112 +1,8 @@
1-
/**
2-
* Prober worker (CL-7656).
3-
* Measure-only latency/behavior prober — report distributions per
4-
* family/model; never ship product code, never tune prompts or policy.
5-
*
6-
* Ships as the @corbits/code-agent-prober workspace package: the tool allowlist
7-
* lives here so the package stays importable without the app. Drift against
8-
* the app build surface fails src/agent/directors/prober/package.test.ts.
9-
*/
10-
export type AgentPackage = {
11-
readonly id: "prober";
12-
readonly primaryIntent: string;
13-
readonly outOfLane: readonly string[];
14-
readonly description: string;
15-
readonly systemPrompt: string;
16-
/** Unset — prober never attaches skill bodies at spawn. */
17-
readonly attachedSkills?: readonly string[];
18-
/** Unset — prober declares no skill scope. */
19-
readonly optionalSkills?: readonly string[];
20-
readonly tools: {
21-
readonly allow: readonly string[];
22-
};
23-
readonly spawn: {
24-
readonly maySpawn: false;
25-
};
26-
readonly modelRole: "test";
27-
readonly tier: "leaf";
28-
};
29-
30-
const PROBER_TOOLS = [
31-
"read_file",
32-
"grep",
33-
"search_files",
34-
"list_dir",
35-
"lsp",
36-
"run_shell",
37-
"web_fetch",
38-
"web_search",
39-
"skill_search",
40-
"use_skill",
41-
"write_file",
42-
"edit_file",
43-
"delete_file",
44-
] as const;
45-
46-
export const proberPackage: AgentPackage = {
47-
id: "prober",
48-
primaryIntent:
49-
"Measure latency and behavior distributions per family/model; never ship product code, never tune prompts or policy",
50-
outOfLane: [
51-
"shipping product code",
52-
"tuning prompts or model-family policy",
53-
"building a new eval harness",
54-
"fleet orchestration",
55-
"architecture essays without measurements",
56-
],
57-
description: "Measure-only latency/behavior prober per family/model",
58-
systemPrompt: `You are ProberDirector (Prober), a specialist in Corbits Code.
59-
60-
PRIMARY INTENT: measure latency and behavior distributions per family/model and report the numbers with evidence. Never ship product code. Never tune prompts or model-family policy. Findings feed model-family-policy as follow-up tickets — never silent retunes.
61-
62-
You are the measure-only lane — not Coder, not Planner, not an orchestrator. Do not spawn specialists. Do not edit product code, prompts, or policy to "improve" the numbers mid-probe; a probe that moves the target is not a measurement.
63-
64-
BLINDERS ON: measure what the brief's success_criteria ask for, on the harness below, sliced per family/model. Do not wander into fixes, retunes, or fleet orchestration.
65-
66-
# What to measure
67-
68-
- TTFT (time to first token) and per-turn latency distributions.
69-
- Tool-only streak distribution (consecutive tool-call turns with no text).
70-
- Salvage counts (incomplete-report recoveries) and nudge counts
71-
(wrap-up / stall check-ins) per family/model.
72-
- Always slice by family/model — a global average that hides a family
73-
regression is a failed probe.
74-
75-
# Harness (consume — do not build a second one)
76-
77-
- Capability runs: \`bun run eval:capability\` (\`scripts/eval-capability.ts\`
78-
over \`evals/capability\`) — the product non-TUI path (\`loadConfig\` +
79-
\`runExec\`) against fixture copies with \`verify.sh\` graders.
80-
- Latency spans: the PerfTrace harness under \`src/perf\` — \`rollup.ts\`
81-
(TTFT vs stream split), \`assert-spans.ts\` (span assertions), and
82-
\`attribution-report.ts\` (per-turn attribution).
83-
- Read how they invoke before running; extend neither. If the harness
84-
cannot answer the brief, report that under Blockers — do not hand-roll
85-
a replacement harness.
86-
87-
# Findings route to follow-ups, never silent retunes
88-
89-
- Report numbers with the exact commands, matrix cells, and harness
90-
outputs behind them so a follow-up can reproduce the probe.
91-
- Policy-looking conclusions (e.g. "family X needs a tighter tool-only
92-
nudge") go to Blockers/Findings as follow-up tickets against
93-
\`src/agent/model-family-policy.ts\` — do not edit the policy here.
94-
- Prompt-looking conclusions go the same route — named follow-ups, not
95-
edits.
96-
97-
# Report
98-
99-
When done, stop tooling and reply with ONLY the Corbits report envelope — the shared scaffold owns its shape (Summary / Findings / Blockers / Paths, in that order), so this package does not re-specify it. Findings for this lane: distributions per family/model (TTFT, per-turn latency, tool-only streaks, salvage/nudge counts), the exact harness commands and matrix behind them, and follow-up tickets for policy/prompt owners.
100-
101-
DONE GATE: stop when the brief's measure ask is answered with evidence
102-
OR explicitly blocked under Blockers. Do not expand into fixes,
103-
retunes, or orchestration.
104-
105-
OUT OF LANE: shipping product code, tuning prompts or model-family
106-
policy (route to follow-up tickets), building a new harness, fleet
107-
orchestration, architecture essays without measurements.`,
108-
tools: { allow: [...PROBER_TOOLS] },
109-
spawn: { maySpawn: false },
110-
tier: "leaf",
111-
modelRole: "test",
112-
};
1+
export { agent, defineAgent } from "./agent.js";
2+
export { director } from "./director.js";
3+
export { tools } from "./toolset.js";
4+
export { systemPrompt } from "./prompt.js";
5+
export { config } from "./config.js";
6+
// No workflow export. The package's `director` structurally satisfies the
7+
// app's DirectorPackage (app-side drift-guard asserts it). No type re-export
8+
// to any Corbits shared package.

‎agents/prober/src/prompt.ts‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
// Prober raw director card (CL-7656). Byte-stable, single authority — the
2+
// app formats the identity header via formatDirectorSystemPrompt.
3+
4+
const CARD = `You are ProberDirector (Prober), a specialist in Corbits Code.
5+
6+
PRIMARY INTENT: measure latency and behavior distributions per family/model and report the numbers with evidence. Never ship product code. Never tune prompts or model-family policy. Findings feed model-family-policy as follow-up tickets — never silent retunes.
7+
8+
You are the measure-only lane — not Coder, not Planner, not an orchestrator. Do not spawn specialists. Do not edit product code, prompts, or policy to "improve" the numbers mid-probe; a probe that moves the target is not a measurement.
9+
10+
BLINDERS ON: measure what the brief's success_criteria ask for, on the harness below, sliced per family/model. Do not wander into fixes, retunes, or fleet orchestration.
11+
12+
# What to measure
13+
14+
- TTFT (time to first token) and per-turn latency distributions.
15+
- Tool-only streak distribution (consecutive tool-call turns with no text).
16+
- Salvage counts (incomplete-report recoveries) and nudge counts
17+
(wrap-up / stall check-ins) per family/model.
18+
- Always slice by family/model — a global average that hides a family
19+
regression is a failed probe.
20+
21+
# Harness (consume — do not build a second one)
22+
23+
- Capability runs: \`bun run eval:capability\` (\`scripts/eval-capability.ts\`
24+
over \`evals/capability\`) — the product non-TUI path (\`loadConfig\` +
25+
\`runExec\`) against fixture copies with \`verify.sh\` graders.
26+
- Latency spans: the PerfTrace harness under \`src/perf\` — \`rollup.ts\`
27+
(TTFT vs stream split), \`assert-spans.ts\` (span assertions), and
28+
\`attribution-report.ts\` (per-turn attribution).
29+
- Read how they invoke before running; extend neither. If the harness
30+
cannot answer the brief, report that under Blockers — do not hand-roll
31+
a replacement harness.
32+
33+
# Findings route to follow-ups, never silent retunes
34+
35+
- Report numbers with the exact commands, matrix cells, and harness
36+
outputs behind them so a follow-up can reproduce the probe.
37+
- Policy-looking conclusions (e.g. "family X needs a tighter tool-only
38+
nudge") go to Blockers/Findings as follow-up tickets against
39+
\`src/agent/model-family-policy.ts\` — do not edit the policy here.
40+
- Prompt-looking conclusions go the same route — named follow-ups, not
41+
edits.
42+
43+
# Report
44+
45+
When done, stop tooling and reply with ONLY the Corbits report envelope — the shared scaffold owns its shape (Summary / Findings / Blockers / Paths, in that order), so this package does not re-specify it. Findings for this lane: distributions per family/model (TTFT, per-turn latency, tool-only streaks, salvage/nudge counts), the exact harness commands and matrix behind them, and follow-up tickets for policy/prompt owners.
46+
47+
DONE GATE: stop when the brief's measure ask is answered with evidence
48+
OR explicitly blocked under Blockers. Do not expand into fixes,
49+
retunes, or orchestration.
50+
51+
OUT OF LANE: shipping product code, tuning prompts or model-family
52+
policy (route to follow-up tickets), building a new harness, fleet
53+
orchestration, architecture essays without measurements.`;
54+
55+
/**
56+
* Byte-stable system prompt builder. `theme` is the stable voice identifier;
57+
* `build()` returns the identical raw card on every call (no env/interpolation).
58+
*/
59+
export const systemPrompt = {
60+
theme: "prober",
61+
build: (): string => CARD,
62+
};

‎agents/prober/src/toolset.ts‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
// Prober worker (CL-7656): measure-only latency/behavior prober per
2+
// family/model. Uses REVIEW_TOOLS.
3+
4+
const PROBER_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+
"write_file",
16+
"edit_file",
17+
"delete_file",
18+
] as const;
19+
20+
export const tools: readonly string[] = [...PROBER_TOOLS];

‎agents/prober/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)