@kealthas-dev/opencode-council 0.0.0-stage → 1.1.5
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +44 -2
- package/council.ts +231 -0
- package/package.json +23 -4
package/README.md
CHANGED
|
@@ -1,3 +1,45 @@
|
|
|
1
|
-
#
|
|
1
|
+
# council
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
A `council` tool and a `/council <question>` command: put one question to several independent advisors in parallel, then have an advisor with no tools compare their answers and rate the consensus. For a decision where one model's single answer is not enough. Where the idea comes from: [docs/multi-agent-prior-art.md](../../docs/multi-agent-prior-art.md).
|
|
4
|
+
|
|
5
|
+
- Package: `@kealthas-dev/opencode-council`, source `council.ts`. It has a real `zod` dependency for the tool's argument schema, like [`llm-review-gate`](../llm-review-gate/README.md). Published; commented out in `deploy/opencode.json.example` as opt-in (see `SETUP.md` step 5).
|
|
6
|
+
|
|
7
|
+
## What happens on a call
|
|
8
|
+
|
|
9
|
+
1. The tool takes `question` and an optional `context` (file paths to read, the options being weighed).
|
|
10
|
+
2. Each seat gets its own child session in the project directory, running the `council-seat` agent with the shared advisor rules plus the seat's own steering prompt. All seats run in parallel. A seat may only `read`, `glob` and `grep`; every other tool, including `council` itself, is denied.
|
|
11
|
+
3. If at least two seats answered, a `council-synth` session, which has no tools at all, gets the question and the answers and replies with `CONSENSUS: unanimous | majority | split`, the answer, and the disagreements. It is told to use only what the advisors wrote and never to present a split as agreement.
|
|
12
|
+
4. The tool returns the synthesis followed by every seat's answer verbatim, so the calling model sees the disagreement itself, not only the summary.
|
|
13
|
+
5. All child sessions are deleted afterwards.
|
|
14
|
+
|
|
15
|
+
Failure handling: a seat that errors, times out or answers nothing is listed as `(no answer: ...)` and left out of the synthesis. One surviving seat is returned as a single opinion with a note that there is nothing to rate. No survivors is an error carrying the reasons. If the synthesis itself fails, the seat answers are still returned. Cancelling the call aborts every child session.
|
|
16
|
+
|
|
17
|
+
The prompts are awaited with `session.prompt`, never fired with `promptAsync`, so the plugin cannot race another hook into injecting a second prompt.
|
|
18
|
+
|
|
19
|
+
## Seats
|
|
20
|
+
|
|
21
|
+
The default seats are `skeptic` (what is wrong or risky), `architect` (structure and long-term cost) and `pragmatist` (the smallest correct thing). They differ by prompt, not by model, so their independence is weaker than with several models; point a seat at another model to strengthen it.
|
|
22
|
+
|
|
23
|
+
Optional config, read on every call so an edit applies without a restart, from `~/.config/kealthas-dev/opencode-council/config.json` (or `config-<name>.json` with `COUNCIL_CONFIG_ENV=<name>`, the same convention as the MCP servers):
|
|
24
|
+
|
|
25
|
+
```json
|
|
26
|
+
{
|
|
27
|
+
"seats": [
|
|
28
|
+
{ "name": "reviewer", "prompt": "Your angle: bugs and failure modes." },
|
|
29
|
+
{ "name": "architect", "prompt": "Your angle: boundaries and long-term cost.", "model": "vllm/other-model" }
|
|
30
|
+
],
|
|
31
|
+
"synthesizer": { "model": "vllm/some-model" },
|
|
32
|
+
"seatTimeoutSeconds": 300,
|
|
33
|
+
"synthTimeoutSeconds": 180
|
|
34
|
+
}
|
|
35
|
+
```
|
|
36
|
+
|
|
37
|
+
At least two seats; `model` is `provider/model` (the model id may itself contain slashes) and defaults to the session's model. A malformed file fails the call with the file name and the problem.
|
|
38
|
+
|
|
39
|
+
## Registration
|
|
40
|
+
|
|
41
|
+
The `config` hook registers the hidden `council-seat` and `council-synth` agents and the `/council` command, only if the user's config does not define them already. The seat agent's permission is `"*": "deny"` followed by `read`, `glob`, `grep` allowed, because the last matching rule wins.
|
|
42
|
+
|
|
43
|
+
## Tests
|
|
44
|
+
|
|
45
|
+
`tests/unit/council.test.mjs` drives the tool with a fake client: seats asked in parallel in the project directory, the synthesis input and report, a failing or empty seat, no answers, a failing synthesis, a hanging seat aborted at its timeout, config and model parsing, cancellation, and agent registration. `tests/integration/guard-plugins.test.mjs` runs it in a real opencode against a fake model and checks which tools each agent was actually offered, that the report reaches the calling model, and that the child sessions are gone afterwards.
|
package/council.ts
ADDED
|
@@ -0,0 +1,231 @@
|
|
|
1
|
+
import { readFile } from "node:fs/promises";
|
|
2
|
+
import { homedir } from "node:os";
|
|
3
|
+
import { join } from "node:path";
|
|
4
|
+
import { z } from "zod";
|
|
5
|
+
import type { Plugin, ToolContext, ToolResult } from "@opencode-ai/plugin";
|
|
6
|
+
|
|
7
|
+
// A `council` tool for decisions where one answer from one model is not enough.
|
|
8
|
+
// Each seat answers independently in its own child session with its own steering
|
|
9
|
+
// prompt; a synthesizer that has no tools then compares the answers. Prompts are
|
|
10
|
+
// awaited with session.prompt, never fired with promptAsync, so nothing here can
|
|
11
|
+
// race another hook into injecting a second prompt (docs/multi-agent-prior-art.md).
|
|
12
|
+
|
|
13
|
+
const SEAT_AGENT = "council-seat";
|
|
14
|
+
const SYNTH_AGENT = "council-synth";
|
|
15
|
+
const COMMAND = "council";
|
|
16
|
+
|
|
17
|
+
const DEFAULT_SEAT_TIMEOUT_S = 300;
|
|
18
|
+
const DEFAULT_SYNTH_TIMEOUT_S = 180;
|
|
19
|
+
|
|
20
|
+
const SEAT_RULES = `You are one of several independent advisors answering the same question; the others cannot see your answer. You may read files (read, glob, grep) but cannot change anything. Answer in at most 250 words: your position in the first sentence, then the reasons that decide it, then what would change your mind. Cite file:line for claims about code. If you cannot tell, say so instead of guessing.`;
|
|
21
|
+
|
|
22
|
+
const DEFAULT_SEATS: Seat[] = [
|
|
23
|
+
{ name: "skeptic", prompt: "Your angle: what is wrong, risky or unstated. Look for bugs, edge cases, failure modes and hidden assumptions in the proposal or in the premise of the question." },
|
|
24
|
+
{ name: "architect", prompt: "Your angle: structure and long-term cost. Look at boundaries, coupling, what is hard to change later, and whether a simpler design does the same job." },
|
|
25
|
+
{ name: "pragmatist", prompt: "Your angle: the smallest correct thing to do. Prefer mechanisms that already exist, and weigh each option by what it costs to build and to verify." },
|
|
26
|
+
];
|
|
27
|
+
|
|
28
|
+
const SYNTH_PROMPT = `You combine the answers of independent advisors to one question. You have no tools and cannot check anything: use only what the advisors wrote, and add no facts of your own.
|
|
29
|
+
|
|
30
|
+
Reply in exactly this form:
|
|
31
|
+
CONSENSUS: unanimous | majority | split
|
|
32
|
+
ANSWER: <the answer the advisors support. If they are split, state each position and which advisors hold it, and do not pick one unless the reasons given clearly decide it.>
|
|
33
|
+
DISAGREEMENTS: <one bullet per point where advisors differ, naming them, or "none">
|
|
34
|
+
|
|
35
|
+
Rate unanimous only if every advisor reaches the same recommendation, majority if more than half do, otherwise split. Never present a split as agreement.`;
|
|
36
|
+
|
|
37
|
+
type Seat = { name: string; prompt: string; model?: string };
|
|
38
|
+
type Config = { seats: Seat[]; synthModel?: string; seatTimeoutS: number; synthTimeoutS: number };
|
|
39
|
+
|
|
40
|
+
const errorMessage = (e: unknown) => (e instanceof Error ? e.message : String(e));
|
|
41
|
+
|
|
42
|
+
// Optional config, re-read on every call so an edit takes effect without a restart.
|
|
43
|
+
// Same location convention as the mcp-servers: config.json, or config-<name>.json when COUNCIL_CONFIG_ENV=<name>.
|
|
44
|
+
async function loadConfig(): Promise<Config> {
|
|
45
|
+
const envName = process.env.COUNCIL_CONFIG_ENV;
|
|
46
|
+
const file = join(homedir(), ".config", "kealthas-dev", "opencode-council", envName ? `config-${envName}.json` : "config.json");
|
|
47
|
+
let raw: unknown = {};
|
|
48
|
+
try {
|
|
49
|
+
raw = JSON.parse(await readFile(file, "utf-8"));
|
|
50
|
+
} catch (e) {
|
|
51
|
+
if ((e as NodeJS.ErrnoException).code !== "ENOENT") throw new Error(`council: cannot read ${file}: ${errorMessage(e)}`);
|
|
52
|
+
}
|
|
53
|
+
const parsed = z
|
|
54
|
+
.object({
|
|
55
|
+
seats: z.array(z.object({ name: z.string().min(1), prompt: z.string().min(1), model: z.string().optional() })).min(2).optional(),
|
|
56
|
+
synthesizer: z.object({ model: z.string().optional() }).optional(),
|
|
57
|
+
seatTimeoutSeconds: z.number().positive().optional(),
|
|
58
|
+
synthTimeoutSeconds: z.number().positive().optional(),
|
|
59
|
+
})
|
|
60
|
+
.safeParse(raw);
|
|
61
|
+
if (!parsed.success) throw new Error(`council: invalid config ${file}: ${parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`).join("; ")}`);
|
|
62
|
+
const c = parsed.data;
|
|
63
|
+
return {
|
|
64
|
+
seats: c.seats ?? DEFAULT_SEATS,
|
|
65
|
+
synthModel: c.synthesizer?.model,
|
|
66
|
+
seatTimeoutS: c.seatTimeoutSeconds ?? DEFAULT_SEAT_TIMEOUT_S,
|
|
67
|
+
synthTimeoutS: c.synthTimeoutSeconds ?? DEFAULT_SYNTH_TIMEOUT_S,
|
|
68
|
+
};
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
// "provider/model" -> the SDK's {providerID, modelID}; the model id itself may contain slashes.
|
|
72
|
+
function parseModel(spec: string | undefined) {
|
|
73
|
+
if (!spec) return undefined;
|
|
74
|
+
const i = spec.indexOf("/");
|
|
75
|
+
if (i <= 0 || i === spec.length - 1) throw new Error(`council: model must look like "provider/model", got "${spec}"`);
|
|
76
|
+
return { providerID: spec.slice(0, i), modelID: spec.slice(i + 1) };
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
// Last rule wins, so the catch-all deny comes first.
|
|
80
|
+
const SEAT_PERMISSION = { "*": "deny", read: "allow", glob: "allow", grep: "allow" };
|
|
81
|
+
const SYNTH_PERMISSION = { "*": "deny" };
|
|
82
|
+
|
|
83
|
+
const councilArgs = {
|
|
84
|
+
question: z.string().describe("The decision or question to put to the council, stated so that it makes sense without the conversation"),
|
|
85
|
+
context: z.string().optional().describe("What the advisors need to know: file paths to read, the options being weighed, constraints"),
|
|
86
|
+
};
|
|
87
|
+
|
|
88
|
+
export const Council: Plugin = async ({ client }) => {
|
|
89
|
+
async function ask(opts: {
|
|
90
|
+
agent: string;
|
|
91
|
+
system: string;
|
|
92
|
+
text: string;
|
|
93
|
+
model?: string;
|
|
94
|
+
timeoutS: number;
|
|
95
|
+
directory: string;
|
|
96
|
+
title: string;
|
|
97
|
+
created: string[];
|
|
98
|
+
signal: AbortSignal;
|
|
99
|
+
}): Promise<string> {
|
|
100
|
+
const session = await client.session.create({ body: { title: opts.title }, query: { directory: opts.directory }, throwOnError: true });
|
|
101
|
+
const id = session.data.id;
|
|
102
|
+
opts.created.push(id);
|
|
103
|
+
let timer: ReturnType<typeof setTimeout> | undefined;
|
|
104
|
+
try {
|
|
105
|
+
const res = await Promise.race([
|
|
106
|
+
client.session.prompt({
|
|
107
|
+
path: { id },
|
|
108
|
+
query: { directory: opts.directory },
|
|
109
|
+
body: { agent: opts.agent, system: opts.system, model: parseModel(opts.model), parts: [{ type: "text", text: opts.text }] },
|
|
110
|
+
throwOnError: true,
|
|
111
|
+
}),
|
|
112
|
+
new Promise<never>((_, reject) => {
|
|
113
|
+
timer = setTimeout(() => {
|
|
114
|
+
void client.session.abort({ path: { id } }).catch(() => {});
|
|
115
|
+
reject(new Error(`timed out after ${opts.timeoutS}s`));
|
|
116
|
+
}, opts.timeoutS * 1000);
|
|
117
|
+
}),
|
|
118
|
+
// The caller cancelled (the user pressed escape): stop waiting at once; execute() aborts the child sessions.
|
|
119
|
+
new Promise<never>((_, reject) => {
|
|
120
|
+
if (opts.signal.aborted) reject(new Error("cancelled"));
|
|
121
|
+
opts.signal.addEventListener("abort", () => reject(new Error("cancelled")), { once: true });
|
|
122
|
+
}),
|
|
123
|
+
]);
|
|
124
|
+
// The whole final message, not just its last text part: a model that writes its answer and then a closing line must not lose the answer.
|
|
125
|
+
const text = (res.data.parts ?? [])
|
|
126
|
+
.filter((p) => p.type === "text")
|
|
127
|
+
.map((p) => (p as unknown as { text: string }).text)
|
|
128
|
+
.join("\n")
|
|
129
|
+
.trim();
|
|
130
|
+
if (!text) throw new Error("empty answer");
|
|
131
|
+
return text;
|
|
132
|
+
} finally {
|
|
133
|
+
if (timer) clearTimeout(timer);
|
|
134
|
+
}
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
async function execute(args: z.infer<z.ZodObject<typeof councilArgs>>, context: ToolContext): Promise<ToolResult> {
|
|
138
|
+
const cfg = await loadConfig();
|
|
139
|
+
const created: string[] = [];
|
|
140
|
+
const stop = () => created.forEach((id) => void client.session.abort({ path: { id } }).catch(() => {}));
|
|
141
|
+
context.abort.addEventListener("abort", stop);
|
|
142
|
+
const question = args.context ? `${args.question}\n\n## Context\n${args.context}` : args.question;
|
|
143
|
+
try {
|
|
144
|
+
context.metadata({ title: `council: ${cfg.seats.length} seats` });
|
|
145
|
+
const answers = await Promise.all(
|
|
146
|
+
cfg.seats.map(async (seat) => {
|
|
147
|
+
try {
|
|
148
|
+
const text = await ask({
|
|
149
|
+
agent: SEAT_AGENT,
|
|
150
|
+
system: `${SEAT_RULES}\n\n${seat.prompt}`,
|
|
151
|
+
text: question,
|
|
152
|
+
model: seat.model,
|
|
153
|
+
timeoutS: cfg.seatTimeoutS,
|
|
154
|
+
directory: context.directory,
|
|
155
|
+
title: `council seat ${seat.name} (internal, safe to delete)`,
|
|
156
|
+
created,
|
|
157
|
+
signal: context.abort,
|
|
158
|
+
});
|
|
159
|
+
return { seat, text };
|
|
160
|
+
} catch (e) {
|
|
161
|
+
return { seat, error: errorMessage(e) };
|
|
162
|
+
}
|
|
163
|
+
}),
|
|
164
|
+
);
|
|
165
|
+
if (context.abort.aborted) throw new Error("council: cancelled");
|
|
166
|
+
|
|
167
|
+
const ok = answers.filter((a): a is { seat: Seat; text: string } => "text" in a);
|
|
168
|
+
const verbatim = answers
|
|
169
|
+
.map((a) => ("text" in a ? `### ${a.seat.name}\n${a.text}` : `### ${a.seat.name}\n(no answer: ${a.error})`))
|
|
170
|
+
.join("\n\n");
|
|
171
|
+
if (ok.length === 0) throw new Error(`council: no seat answered.\n\n${verbatim}`);
|
|
172
|
+
const header = `# Council report (${ok.length} of ${answers.length} seats answered)`;
|
|
173
|
+
if (ok.length === 1) {
|
|
174
|
+
return `${header}\n\nOnly one seat answered, so there is no consensus to rate; read its answer as one opinion.\n\n## Seat answers (verbatim)\n${verbatim}`;
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
let synthesis: string;
|
|
178
|
+
try {
|
|
179
|
+
synthesis = await ask({
|
|
180
|
+
agent: SYNTH_AGENT,
|
|
181
|
+
system: SYNTH_PROMPT,
|
|
182
|
+
text: `## Question\n${question}\n\n## Advisor answers\n${ok.map((a) => `### ${a.seat.name}\n${a.text}`).join("\n\n")}`,
|
|
183
|
+
model: cfg.synthModel,
|
|
184
|
+
timeoutS: cfg.synthTimeoutS,
|
|
185
|
+
directory: context.directory,
|
|
186
|
+
title: "council synthesis (internal, safe to delete)",
|
|
187
|
+
created,
|
|
188
|
+
signal: context.abort,
|
|
189
|
+
});
|
|
190
|
+
} catch (e) {
|
|
191
|
+
// The seat answers are the valuable part; never lose them because the summary failed.
|
|
192
|
+
return `${header}\n\nThe synthesis failed (${errorMessage(e)}), so there is no consensus rating; compare the answers yourself.\n\n## Seat answers (verbatim)\n${verbatim}`;
|
|
193
|
+
}
|
|
194
|
+
return `${header}\n\n${synthesis}\n\n## Seat answers (verbatim)\n${verbatim}`;
|
|
195
|
+
} finally {
|
|
196
|
+
context.abort.removeEventListener("abort", stop);
|
|
197
|
+
await Promise.all(created.map((id) => client.session.delete({ path: { id } }).catch(() => {})));
|
|
198
|
+
}
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
return {
|
|
202
|
+
tool: {
|
|
203
|
+
[COMMAND]: {
|
|
204
|
+
description:
|
|
205
|
+
"Put a question to several independent advisors and get their answers compared. Use it for a decision where being wrong is costly or the answer is genuinely contested, or when the user asks for a second opinion or several views. Costs several model calls, so do not use it for routine questions. Returns a consensus rating (unanimous, majority or split), the combined answer, the disagreements and every advisor's own answer.",
|
|
206
|
+
args: councilArgs,
|
|
207
|
+
execute,
|
|
208
|
+
},
|
|
209
|
+
},
|
|
210
|
+
config: async (config) => {
|
|
211
|
+
config.agent ??= {};
|
|
212
|
+
config.agent[SEAT_AGENT] ??= {
|
|
213
|
+
description: "Read-only advisor used by the council tool. Not user-facing.",
|
|
214
|
+
mode: "subagent",
|
|
215
|
+
hidden: true,
|
|
216
|
+
permission: SEAT_PERMISSION as never,
|
|
217
|
+
};
|
|
218
|
+
config.agent[SYNTH_AGENT] ??= {
|
|
219
|
+
description: "Tool-less synthesizer used by the council tool. Not user-facing.",
|
|
220
|
+
mode: "subagent",
|
|
221
|
+
hidden: true,
|
|
222
|
+
permission: SYNTH_PERMISSION as never,
|
|
223
|
+
};
|
|
224
|
+
config.command ??= {};
|
|
225
|
+
config.command[COMMAND] ??= {
|
|
226
|
+
description: "Ask several independent advisors and compare their answers (usage: /council <question>)",
|
|
227
|
+
template: `Call the ${COMMAND} tool with the question below as its question, and put anything the advisors need in context (file paths to read, the options being weighed). Then report the council's consensus rating and answer, any disagreements, and each advisor's own answer.\n\n$ARGUMENTS`,
|
|
228
|
+
};
|
|
229
|
+
},
|
|
230
|
+
};
|
|
231
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,25 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@kealthas-dev/opencode-council",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
|
|
3
|
+
"version": "1.1.5",
|
|
4
|
+
"type": "module",
|
|
5
|
+
"description": "council.ts opencode plugin: a council tool and /council command that put a question to several independent advisors in parallel and have a tool-less synthesizer rate the consensus (unanimous, majority, split). Written in TypeScript against @opencode-ai/plugin's Plugin type (type-only) plus a real zod runtime dependency for the tool's argument schema. Independently installable - not bundled with the other plugins.",
|
|
6
|
+
"main": "council.ts",
|
|
7
|
+
"files": [
|
|
8
|
+
"council.ts"
|
|
9
|
+
],
|
|
10
|
+
"publishConfig": {
|
|
11
|
+
"access": "public"
|
|
12
|
+
},
|
|
13
|
+
"repository": {
|
|
14
|
+
"type": "git",
|
|
15
|
+
"url": "https://github.com/Keal-thas/opencode-toolkit.git",
|
|
16
|
+
"directory": "plugins/council"
|
|
17
|
+
},
|
|
18
|
+
"dependencies": {
|
|
19
|
+
"zod": "^4.1.8"
|
|
20
|
+
},
|
|
21
|
+
"devDependencies": {
|
|
22
|
+
"@opencode-ai/plugin": "^1.0.0",
|
|
23
|
+
"@types/node": "^22.0.0"
|
|
24
|
+
}
|
|
25
|
+
}
|