IdeaSDK/docs/commands-and-feedback.md

Commands And Feedback

This document is the normative SDK contract for plugin commands that may launch background work.

Contract

Every human menu click follows this sequence:

menu item -> command id -> registered command handler -> optional task -> feedback surfaces

• A manifest menu item declares a command id; it does not run tools directly.
• The command handler is the only place that decides whether work should start.
• A launched process is represented by a background task returned from ctx.services.tasks.runCommand().
• A skipped command is represented by the command handler return value and logs, not by a fake task.
• Feedback objects must be stable enough for agents and programmatic callers to parse, and their messages must be readable by humans.
• The current human menu-click UI does not guarantee display of a command handler return value. Use logs, Work/task state or plugin-owned UI/files when a human needs visible feedback today.

Preconditions

Check preconditions before calling runCommand():

• ctx.services exists. Plugins need the tooling capability for the service facade.
• ctx.services.workspace.getCurrentProject() returned a project, or the caller supplied a valid projectId.
• Required executables, environment variables and workspace files were validated, preferably with ctx.services.tooling.diagnose().
• ownerAgentId is a real agent id when the work is owned by an agent workflow. Do not use all-zero placeholders in production.
• cwd is relative to the project root.
• command and args are separate values. Do not shell-join user input.

If any required precondition fails, return a skipped result:

return {
  status: "skipped",
  reason: "missing-owner-agent",
  message: "Configure an owner agent before launching the hello-plugin task."
};

Feedback Surfaces

Command handlers should return one of these shapes, or a plugin-specific object with equivalent fields:

type CommandFeedback =
  | { status: "skipped"; reason: string; message: string }
  | { status: "launched"; taskId: string; state: string; message: string };

Use the same status vocabulary consistently:

• skipped: no background task was created.
• launched: a task was created; inspect the task state for later progress.
• failed: the handler itself failed before it could return normally.

Visible surfaces are intentionally distinct:

• Command return value: immediate feedback for programmatic callers, agents and future host surfaces. It is not a guaranteed visible UI surface for current human menu clicks.
• Plugin logs: diagnostics for developers and operators.
• Work/background-task surfaces: only for tasks actually launched through runCommand().
• Plugin layouts or files: optional plugin-owned user feedback.

recordOnly: true affects completion delivery to the owning agent. It does not mean hidden, skipped or UI-silent. A record-only command task can still appear in Work and can still emit background-task events.

Best-Effort Watches

ctx.services.workspace.watch() is not a baseline precondition for commands. The host may reject it until workspace watch support is delivered. Treat watch setup as optional and non-fatal:

try {
  const watch = await ctx.services.workspace.watch(".ideai", refresh, project.id);
  ctx.subscriptions.push(watch);
} catch (error) {
  ctx.logger.info("workspace watch unavailable", { error });
}

Commands that depend on fresh workspace state should refresh or re-read that state when invoked instead of assuming a watch was installed at activation.

Example

const project = await ctx.services?.workspace.getCurrentProject();
if (!project) {
  return {
    status: "skipped",
    reason: "no-focused-project",
    message: "Open a project before running this command."
  };
}

const ownerAgentId = await ctx.storage?.get<string>("myPlugin.ownerAgentId");
if (!ownerAgentId) {
  return {
    status: "skipped",
    reason: "missing-owner-agent",
    message: "Configure an owner agent before launching this task."
  };
}

const task = await ctx.services.tasks.runCommand({
  projectId: project.id,
  ownerAgentId,
  label: "Run my tool",
  command: "npm",
  args: ["--version"],
  cwd: ".",
  recordOnly: true
});

return {
  status: "launched",
  taskId: task.taskId,
  state: task.state,
  message: "Started Run my tool."
};

Counterexample

Do not launch a shell command just to produce feedback:

await ctx.services?.tasks.runCommand({
  ownerAgentId: "00000000-0000-0000-0000-000000000000",
  label: "Skipped: missing config",
  command: "echo",
  args: ["missing config"],
  recordOnly: true
});

This creates misleading Work history, uses a placeholder owner and turns a precondition failure into a fake task. Return status: "skipped" instead.