feat: add task_update and task_comment tools (#33)
Closes #26 This PR adds two new DevClaw tools for better task lifecycle management: - task_update: Change issue state programmatically without full pickup/complete flow - task_comment: Add review comments or notes to issues with optional role attribution
This commit is contained in:
Lauren ten Hoor
GitHub
134
lib/tools/task-comment.ts
Normal file
134
lib/tools/task-comment.ts
Normal file
@@ -0,0 +1,134 @@
|
||||
/**
|
||||
* task_comment — Add review comments or notes to an issue.
|
||||
*
|
||||
* Use cases:
|
||||
* - QA worker adds review feedback without blocking pass/fail
|
||||
* - DEV worker posts implementation notes
|
||||
* - Orchestrator adds summary comments
|
||||
*/
|
||||
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
|
||||
import { jsonResult } from "openclaw/plugin-sdk";
|
||||
import type { ToolContext } from "../types.js";
|
||||
import { readProjects } from "../projects.js";
|
||||
import { createProvider } from "../task-managers/index.js";
|
||||
import { log as auditLog } from "../audit.js";
|
||||
|
||||
/** Valid author roles for attribution */
|
||||
const AUTHOR_ROLES = ["dev", "qa", "orchestrator"] as const;
|
||||
type AuthorRole = (typeof AUTHOR_ROLES)[number];
|
||||
|
||||
export function createTaskCommentTool(api: OpenClawPluginApi) {
|
||||
return (ctx: ToolContext) => ({
|
||||
name: "task_comment",
|
||||
label: "Task Comment",
|
||||
description: `Add a comment to an issue. Use this for review feedback, implementation notes, or any discussion that doesn't require a state change.
|
||||
|
||||
Use cases:
|
||||
- QA adds review feedback without blocking pass/fail
|
||||
- DEV posts implementation notes or progress updates
|
||||
- Orchestrator adds summary comments
|
||||
- Cross-referencing related issues or PRs
|
||||
|
||||
Examples:
|
||||
- Simple: { projectGroupId: "-123456789", issueId: 42, body: "Found an edge case with null inputs" }
|
||||
- With role: { projectGroupId: "-123456789", issueId: 42, body: "LGTM!", authorRole: "qa" }
|
||||
- Detailed: { projectGroupId: "-123456789", issueId: 42, body: "## Notes\\n\\n- Tested on staging\\n- All checks passing", authorRole: "dev" }`,
|
||||
parameters: {
|
||||
type: "object",
|
||||
required: ["projectGroupId", "issueId", "body"],
|
||||
properties: {
|
||||
projectGroupId: {
|
||||
type: "string",
|
||||
description: "Telegram/WhatsApp group ID (key in projects.json)",
|
||||
},
|
||||
issueId: {
|
||||
type: "number",
|
||||
description: "Issue ID to comment on",
|
||||
},
|
||||
body: {
|
||||
type: "string",
|
||||
description: "Comment body in markdown. Supports GitHub-flavored markdown.",
|
||||
},
|
||||
authorRole: {
|
||||
type: "string",
|
||||
enum: AUTHOR_ROLES,
|
||||
description: `Optional role attribution for the comment. One of: ${AUTHOR_ROLES.join(", ")}`,
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
async execute(_id: string, params: Record<string, unknown>) {
|
||||
const groupId = params.projectGroupId as string;
|
||||
const issueId = params.issueId as number;
|
||||
const body = params.body as string;
|
||||
const authorRole = (params.authorRole as AuthorRole) ?? undefined;
|
||||
const workspaceDir = ctx.workspaceDir;
|
||||
|
||||
if (!workspaceDir) {
|
||||
throw new Error("No workspace directory available in tool context");
|
||||
}
|
||||
|
||||
// Validate body is not empty
|
||||
if (!body || body.trim().length === 0) {
|
||||
throw new Error("Comment body cannot be empty.");
|
||||
}
|
||||
|
||||
// 1. Resolve project
|
||||
const data = await readProjects(workspaceDir);
|
||||
const project = data.projects[groupId];
|
||||
if (!project) {
|
||||
throw new Error(
|
||||
`Project not found for groupId ${groupId}. Run project_register first.`,
|
||||
);
|
||||
}
|
||||
|
||||
// 2. Create provider
|
||||
const { provider, type: providerType } = createProvider({
|
||||
repo: project.repo,
|
||||
});
|
||||
|
||||
// 3. Fetch issue to verify it exists and get title
|
||||
const issue = await provider.getIssue(issueId);
|
||||
|
||||
// 4. Prepare comment body with optional attribution header
|
||||
let commentBody = body;
|
||||
if (authorRole) {
|
||||
const roleEmoji: Record<AuthorRole, string> = {
|
||||
dev: "👨💻",
|
||||
qa: "🔍",
|
||||
orchestrator: "🎛️",
|
||||
};
|
||||
commentBody = `${roleEmoji[authorRole]} **${authorRole.toUpperCase()}**: ${body}`;
|
||||
}
|
||||
|
||||
// 5. Add the comment
|
||||
await provider.addComment(issueId, commentBody);
|
||||
|
||||
// 6. Audit log
|
||||
await auditLog(workspaceDir, "task_comment", {
|
||||
project: project.name,
|
||||
groupId,
|
||||
issueId,
|
||||
authorRole: authorRole ?? null,
|
||||
bodyPreview: body.slice(0, 100) + (body.length > 100 ? "..." : ""),
|
||||
provider: providerType,
|
||||
});
|
||||
|
||||
// 7. Build response
|
||||
const result = {
|
||||
success: true,
|
||||
issueId,
|
||||
issueTitle: issue.title,
|
||||
issueUrl: issue.web_url,
|
||||
commentAdded: true,
|
||||
authorRole: authorRole ?? null,
|
||||
bodyLength: body.length,
|
||||
project: project.name,
|
||||
provider: providerType,
|
||||
announcement: `💬 Comment added to #${issueId}${authorRole ? ` by ${authorRole.toUpperCase()}` : ""}`,
|
||||
};
|
||||
|
||||
return jsonResult(result);
|
||||
},
|
||||
});
|
||||
}
|
||||
144
lib/tools/task-update.ts
Normal file
144
lib/tools/task-update.ts
Normal file
@@ -0,0 +1,144 @@
|
||||
/**
|
||||
* task_update — Change issue state programmatically.
|
||||
*
|
||||
* Use cases:
|
||||
* - Orchestrator or worker needs to change state without full pickup/complete flow
|
||||
* - Manual status adjustments (e.g., Planning → To Do after approval)
|
||||
* - Failed auto-transitions that need correction
|
||||
*/
|
||||
import type { OpenClawPluginApi } from "openclaw/plugin-sdk";
|
||||
import { jsonResult } from "openclaw/plugin-sdk";
|
||||
import type { ToolContext } from "../types.js";
|
||||
import { readProjects } from "../projects.js";
|
||||
import { createProvider } from "../task-managers/index.js";
|
||||
import { log as auditLog } from "../audit.js";
|
||||
import type { StateLabel } from "../task-managers/task-manager.js";
|
||||
|
||||
const STATE_LABELS: StateLabel[] = [
|
||||
"Planning",
|
||||
"To Do",
|
||||
"Doing",
|
||||
"To Test",
|
||||
"Testing",
|
||||
"Done",
|
||||
"To Improve",
|
||||
"Refining",
|
||||
];
|
||||
|
||||
export function createTaskUpdateTool(api: OpenClawPluginApi) {
|
||||
return (ctx: ToolContext) => ({
|
||||
name: "task_update",
|
||||
label: "Task Update",
|
||||
description: `Change issue state programmatically. Use this when you need to update an issue's status without going through the full pickup/complete flow.
|
||||
|
||||
Use cases:
|
||||
- Orchestrator or worker needs to change state manually
|
||||
- Manual status adjustments (e.g., Planning → To Do after approval)
|
||||
- Failed auto-transitions that need correction
|
||||
- Bulk state changes
|
||||
|
||||
Examples:
|
||||
- Simple: { projectGroupId: "-123456789", issueId: 42, state: "To Do" }
|
||||
- With reason: { projectGroupId: "-123456789", issueId: 42, state: "To Do", reason: "Approved for development" }`,
|
||||
parameters: {
|
||||
type: "object",
|
||||
required: ["projectGroupId", "issueId", "state"],
|
||||
properties: {
|
||||
projectGroupId: {
|
||||
type: "string",
|
||||
description: "Telegram/WhatsApp group ID (key in projects.json)",
|
||||
},
|
||||
issueId: {
|
||||
type: "number",
|
||||
description: "Issue ID to update",
|
||||
},
|
||||
state: {
|
||||
type: "string",
|
||||
enum: STATE_LABELS,
|
||||
description: `New state for the issue. One of: ${STATE_LABELS.join(", ")}`,
|
||||
},
|
||||
reason: {
|
||||
type: "string",
|
||||
description: "Optional audit log reason for the state change",
|
||||
},
|
||||
},
|
||||
},
|
||||
|
||||
async execute(_id: string, params: Record<string, unknown>) {
|
||||
const groupId = params.projectGroupId as string;
|
||||
const issueId = params.issueId as number;
|
||||
const newState = params.state as StateLabel;
|
||||
const reason = (params.reason as string) ?? undefined;
|
||||
const workspaceDir = ctx.workspaceDir;
|
||||
|
||||
if (!workspaceDir) {
|
||||
throw new Error("No workspace directory available in tool context");
|
||||
}
|
||||
|
||||
// 1. Resolve project
|
||||
const data = await readProjects(workspaceDir);
|
||||
const project = data.projects[groupId];
|
||||
if (!project) {
|
||||
throw new Error(
|
||||
`Project not found for groupId ${groupId}. Run project_register first.`,
|
||||
);
|
||||
}
|
||||
|
||||
// 2. Create provider
|
||||
const { provider, type: providerType } = createProvider({
|
||||
repo: project.repo,
|
||||
});
|
||||
|
||||
// 3. Fetch current issue to get current state
|
||||
const issue = await provider.getIssue(issueId);
|
||||
const currentState = provider.getCurrentStateLabel(issue);
|
||||
|
||||
if (!currentState) {
|
||||
throw new Error(
|
||||
`Issue #${issueId} has no recognized state label. Cannot perform transition.`,
|
||||
);
|
||||
}
|
||||
|
||||
if (currentState === newState) {
|
||||
return jsonResult({
|
||||
success: true,
|
||||
issueId,
|
||||
state: newState,
|
||||
changed: false,
|
||||
message: `Issue #${issueId} is already in state "${newState}".`,
|
||||
project: project.name,
|
||||
provider: providerType,
|
||||
});
|
||||
}
|
||||
|
||||
// 4. Perform the transition
|
||||
await provider.transitionLabel(issueId, currentState, newState);
|
||||
|
||||
// 5. Audit log
|
||||
await auditLog(workspaceDir, "task_update", {
|
||||
project: project.name,
|
||||
groupId,
|
||||
issueId,
|
||||
fromState: currentState,
|
||||
toState: newState,
|
||||
reason: reason ?? null,
|
||||
provider: providerType,
|
||||
});
|
||||
|
||||
// 6. Build response
|
||||
const result = {
|
||||
success: true,
|
||||
issueId,
|
||||
issueTitle: issue.title,
|
||||
state: newState,
|
||||
changed: true,
|
||||
labelTransition: `${currentState} → ${newState}`,
|
||||
project: project.name,
|
||||
provider: providerType,
|
||||
announcement: `🔄 Updated #${issueId}: "${currentState}" → "${newState}"${reason ? ` (${reason})` : ""}`,
|
||||
};
|
||||
|
||||
return jsonResult(result);
|
||||
},
|
||||
});
|
||||
}
|
||||
Reference in New Issue
Block a user