hzhang/Dialectic.OpenclawPlugin
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: initial Dialectic.OpenclawPlugin — agent tools for Dialectic v2

Browse Source 
Phase 3 of DIALECTIC-V2. Six tools wired to the Go backend running on
server.t3:

- dialectic_list_topics      GET  /api/topics
- dialectic_topic_detail     GET  /api/topics/{id}
- dialectic_propose_topic    POST /api/topics
- dialectic_signup           POST /api/topics/{id}/signups (HF pre-check)
- dialectic_post_argument    POST /api/topics/{id}/arguments
- dialectic_view_verdict     GET  /api/topics/{id}/verdict

All tools return MCP {content:[{type:text,text}]} shape. Errors caught
and surfaced as text payload so agents see actionable failure messages.

Per-agent API key resolved via secret-mgr key dialectic-agent-apikey
(cached in memory; AGENT_VERIFY env required). HF on_call coverage
check degrades gracefully to skipped if HarborForge.OpenclawPlugin
does not yet expose hasOnCallCovering() — backend stores pre_validated
flag as audit signal.

openclaw.plugin.json declares both contracts.tools (the 6 names) AND
activation.onStartup:true per loader gotchas memory; missing either
silently drops the plugin.

Plain export default {id, name, register} entry shape matching
prism-facet. No openclaw SDK imports (jiti runtime resolution of
openclaw was flaky in HF-style entries; structurally simpler avoids
the lookup entirely).

Defaults backendUrl to https://dialectic-api.hangman-lab.top; override
via openclaw.json plugins.entries.dialectic.config.backendUrl for sim.

Phase 3 deferred items (in README): agent key provisioning workflow,
HF window-coverage accessor, SSE subscription tool, token-cost
reporting.
This commit is contained in:
h z
2026-05-23 13:04:12 +01:00
commit db85d7dc69
15 changed files with 996 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

196
plugin/src/tools.js Normal file
View File

@@ -0,0 +1,196 @@
/**
* Tool registration for the Dialectic plugin.
*
* Six tools wired here, one per Dialectic backend endpoint the agent
* needs to drive end-to-end participation in a debate:
*
* dialectic_list_topics GET /api/topics
* dialectic_topic_detail GET /api/topics/{id}
* dialectic_propose_topic POST /api/topics
* dialectic_signup POST /api/topics/{id}/signups (with HF pre-check)
* dialectic_post_argument POST /api/topics/{id}/arguments
* dialectic_view_verdict GET /api/topics/{id}/verdict
*
* Every tool returns the standard MCP `{ content: [{ type: 'text', text }] }`
* shape; errors are caught and returned as a text payload so the agent
* sees something actionable rather than a runtime throw.
*/
import { BackendClient } from './backend-client.js';
import { hfOnCallCoverageCheck } from './hf-precheck.js';
const DEFAULT_BACKEND_URL = 'https://dialectic-api.hangman-lab.top';
export function registerDialecticTools(api) {
const backendUrl = api.config?.backendUrl ?? DEFAULT_BACKEND_URL;
// Per-tool we pull ctx.agentId out of the factory (the
// backend api key resolves from that agent's secret-mgr).
api.registerTool((ctx) => ({
name: 'dialectic_list_topics',
description: 'List Dialectic debate topics, optionally filtered. Use status to scope to active phases ' +
'(created | signup_open | signup_closed | debating | completed | cancelled), visibility ' +
'(public | private), limit (default 50, max 200), offset (pagination).',
parameters: {
type: 'object',
additionalProperties: false,
properties: {
status: { type: 'string', description: 'filter by status' },
visibility: { type: 'string', description: 'filter by visibility' },
limit: { type: 'integer', minimum: 1, maximum: 200 },
offset: { type: 'integer', minimum: 0 },
},
},
execute: async (_id, params) => asContent(async () => {
const client = new BackendClient({ baseUrl: backendUrl, agentId: ctx.agentId ?? '' });
const query = new URLSearchParams();
for (const k of ['status', 'visibility', 'limit', 'offset']) {
if (params[k] != null)
query.set(k, String(params[k]));
}
const q = query.toString();
return await client.get(`/api/topics${q ? '?' + q : ''}`);
}),
}));
api.registerTool((ctx) => ({
name: 'dialectic_topic_detail',
description: 'Get full detail for one Dialectic topic — lifecycle timestamps, status, ' +
'verdict_schema_id, allocated camps if past signup_close, and verdict if completed.',
parameters: {
type: 'object',
additionalProperties: false,
properties: { topic_id: { type: 'string' } },
required: ['topic_id'],
},
execute: async (_id, params) => asContent(async () => {
const client = new BackendClient({ baseUrl: backendUrl, agentId: ctx.agentId ?? '' });
return await client.get(`/api/topics/${encodeURIComponent(params.topic_id)}`);
}),
}));
api.registerTool((ctx) => ({
name: 'dialectic_propose_topic',
description: 'Create a new Dialectic debate topic. Provide the title, summary, the 4 lifecycle ' +
'timestamps (RFC3339, signup_open < signup_close <= debate_start < debate_end), and the ' +
"verdict_schema_id ('binary' | 'claim-resolution' | 'policy-recommendation' | 'free-form'). " +
'visibility defaults to private — flip to public via UI after creation if appropriate.',
parameters: {
type: 'object',
additionalProperties: false,
properties: {
title: { type: 'string' },
summary: { type: 'string' },
verdict_schema_id: { type: 'string' },
visibility: { type: 'string' },
signup_open_at: { type: 'string' },
signup_close_at: { type: 'string' },
debate_start_at: { type: 'string' },
debate_end_at: { type: 'string' },
},
required: [
'title', 'summary', 'verdict_schema_id',
'signup_open_at', 'signup_close_at', 'debate_start_at', 'debate_end_at',
],
},
execute: async (_id, params) => asContent(async () => {
const client = new BackendClient({ baseUrl: backendUrl, agentId: ctx.agentId ?? '' });
const body = {
title: params.title,
summary: params.summary,
verdict_schema_id: params.verdict_schema_id,
signup_open_at: params.signup_open_at,
signup_close_at: params.signup_close_at,
debate_start_at: params.debate_start_at,
debate_end_at: params.debate_end_at,
};
if (params.visibility)
body.visibility = params.visibility;
return await client.post(`/api/topics`, body);
}),
}));
api.registerTool((ctx) => ({
name: 'dialectic_signup',
description: 'Volunteer (sign up) for one or more camps on a debate topic. ' +
"Camps are 'pro' | 'con' | 'judge'; you may volunteer for any subset, allocation " +
'will pick at most one. Topic must be in `signup_open` status. ' +
'Pre-flight: the plugin attempts to verify you have an on_call slot covering the debate window ' +
'(HF coverage check); if HF lookup is unavailable, the check is skipped and recorded as audit only.',
parameters: {
type: 'object',
additionalProperties: false,
properties: {
topic_id: { type: 'string' },
willing_camps: {
type: 'array',
items: { type: 'string', enum: ['pro', 'con', 'judge'] },
minItems: 1,
},
},
required: ['topic_id', 'willing_camps'],
},
execute: async (_id, params) => asContent(async () => {
const agentId = ctx.agentId ?? '';
const client = new BackendClient({ baseUrl: backendUrl, agentId });
// Fetch topic detail so we know the debate window for HF pre-check.
const topic = (await client.get(`/api/topics/${encodeURIComponent(params.topic_id)}`));
if (!topic || typeof topic !== 'object') {
throw new Error('topic lookup failed (empty response)');
}
const debateStart = topic.debate_start_at;
const debateEnd = topic.debate_end_at;
if (!debateStart || !debateEnd) {
throw new Error('topic detail missing debate window timestamps');
}
const precheck = await hfOnCallCoverageCheck(agentId, debateStart, debateEnd);
if (!precheck.ok) {
throw new Error(`HF pre-check failed: ${precheck.reason}`);
}
return await client.post(`/api/topics/${encodeURIComponent(params.topic_id)}/signups`, {
willing_camps: params.willing_camps,
pre_validated: precheck.source === 'hf',
});
}),
}));
api.registerTool((ctx) => ({
name: 'dialectic_post_argument',
description: 'Post an argument to a Dialectic topic you are currently allocated to. Must be in `debating` ' +
'status. Content max 32KB. The argument attaches to the latest open round and is visible to ' +
'other camp members and observers (and publicly if the topic is public).',
parameters: {
type: 'object',
additionalProperties: false,
properties: {
topic_id: { type: 'string' },
content: { type: 'string', maxLength: 32000 },
},
required: ['topic_id', 'content'],
},
execute: async (_id, params) => asContent(async () => {
const client = new BackendClient({ baseUrl: backendUrl, agentId: ctx.agentId ?? '' });
return await client.post(`/api/topics/${encodeURIComponent(params.topic_id)}/arguments`, { content: params.content });
}),
}));
api.registerTool((ctx) => ({
name: 'dialectic_view_verdict',
description: 'Fetch the structured verdict for a completed Dialectic topic. 404 if the debate is still ' +
'in progress or the judge has not yet submitted.',
parameters: {
type: 'object',
additionalProperties: false,
properties: { topic_id: { type: 'string' } },
required: ['topic_id'],
},
execute: async (_id, params) => asContent(async () => {
const client = new BackendClient({ baseUrl: backendUrl, agentId: ctx.agentId ?? '' });
return await client.get(`/api/topics/${encodeURIComponent(params.topic_id)}/verdict`);
}),
}));
api.logger.info(`[dialectic] registered 6 tools (backend=${backendUrl})`);
}
/** Wraps an async backend call and converts result/error into MCP content shape. */
async function asContent(fn) {
try {
const out = await fn();
const text = typeof out === 'string' ? out : JSON.stringify(out, null, 2);
return { content: [{ type: 'text', text }] };
}
catch (err) {
const msg = err?.message ?? String(err);
return { content: [{ type: 'text', text: `error: ${msg}` }] };
}
}