clawspec 1.0.0

package/src/config.ts

@@ -0,0 +1,220 @@
+import {
+  getDefaultWorkspacePath,
+  resolveUserPath,
+} from "./utils/paths.ts";
+import type { OpenClawPluginConfigSchema } from "openclaw/plugin-sdk";
+
+export type ClawSpecPluginConfig = {
+  enabled: boolean;
+  allowedChannels?: string[];
+  openSpecTimeoutMs: number;
+  maxAutoContinueTurns: number;
+  maxNoProgressTurns: number;
+  workerWaitTimeoutMs: number;
+  workerAgentId: string;
+  workerBackendId?: string;
+  watcherPollIntervalMs: number;
+  subagentLane?: string;
+  archiveDirName: string;
+  defaultWorkspace: string;
+};
+
+export const clawspecPluginConfigSchema: OpenClawPluginConfigSchema = {
+  jsonSchema: {
+    type: "object",
+    additionalProperties: false,
+    properties: {
+      enabled: { type: "boolean" },
+      allowedChannels: {
+        type: "array",
+        items: { type: "string" },
+      },
+      maxAutoContinueTurns: {
+        type: "integer",
+        minimum: 1,
+        maximum: 50,
+      },
+      maxNoProgressTurns: {
+        type: "integer",
+        minimum: 1,
+        maximum: 10,
+      },
+      openSpecTimeoutMs: {
+        type: "integer",
+        minimum: 5_000,
+        maximum: 600_000,
+      },
+      workerWaitTimeoutMs: {
+        type: "integer",
+        minimum: 10_000,
+        maximum: 3_600_000,
+      },
+      workerAgentId: {
+        type: "string",
+      },
+      workerBackendId: {
+        type: "string",
+      },
+      watcherPollIntervalMs: {
+        type: "integer",
+        minimum: 1_000,
+        maximum: 60_000,
+      },
+      subagentLane: {
+        type: "string",
+      },
+      archiveDirName: {
+        type: "string",
+      },
+      defaultWorkspace: {
+        type: "string",
+      },
+    },
+  },
+  validate(value) {
+    const parsed = parsePluginConfig((value ?? {}) as Record<string, unknown>);
+    return { ok: true, value: parsed };
+  },
+  uiHints: {
+    enabled: {
+      label: "Enable ClawSpec",
+      help: "Enable or disable the ClawSpec plugin",
+    },
+    allowedChannels: {
+      label: "Allowed Channels",
+      help: "Optional list of channel ids allowed to use /clawspec",
+    },
+    maxAutoContinueTurns: {
+      label: "Deprecated Auto Turns",
+      help: "Deprecated no-op retained for backward compatibility with older configs",
+      advanced: true,
+    },
+    maxNoProgressTurns: {
+      label: "Deprecated No Progress",
+      help: "Deprecated no-op retained for backward compatibility with older configs",
+      advanced: true,
+    },
+    openSpecTimeoutMs: {
+      label: "OpenSpec Timeout",
+      help: "Timeout in milliseconds for each OpenSpec command",
+      advanced: true,
+    },
+    workerWaitTimeoutMs: {
+      label: "Deprecated Worker Timeout",
+      help: "Deprecated no-op retained for backward compatibility with older configs",
+      advanced: true,
+    },
+    workerAgentId: {
+      label: "Worker Agent",
+      help: "Agent id used for background ACP planning and implementation turns",
+      advanced: true,
+    },
+    workerBackendId: {
+      label: "Deprecated Worker Backend",
+      help: "Deprecated no-op retained for backward compatibility with older configs",
+      advanced: true,
+    },
+    watcherPollIntervalMs: {
+      label: "Watcher Poll Interval",
+      help: "Background watcher recovery poll interval in milliseconds",
+      advanced: true,
+    },
+    subagentLane: {
+      label: "Deprecated Lane Hint",
+      help: "Deprecated no-op retained for backward compatibility with older configs",
+      advanced: true,
+    },
+    archiveDirName: {
+      label: "Archive Folder",
+      help: "Directory name for archived project bundles",
+      advanced: true,
+    },
+    defaultWorkspace: {
+      label: "Default Workspace",
+      help: "Default workspace used for `/clawspec workspace` and `/clawspec use`",
+    },
+  },
+};
+
+const DEFAULT_CONFIG: ClawSpecPluginConfig = {
+  enabled: true,
+  maxAutoContinueTurns: 3,
+  maxNoProgressTurns: 2,
+  openSpecTimeoutMs: 120_000,
+  workerWaitTimeoutMs: 300_000,
+  workerAgentId: "codex",
+  watcherPollIntervalMs: 4_000,
+  archiveDirName: "archives",
+  defaultWorkspace: getDefaultWorkspacePath(),
+};
+
+export function parsePluginConfig(
+  value: Record<string, unknown> | undefined,
+): ClawSpecPluginConfig {
+  const config = value ?? {};
+  return {
+    enabled: asBoolean(config.enabled, DEFAULT_CONFIG.enabled),
+    allowedChannels: Array.isArray(config.allowedChannels)
+      ? config.allowedChannels.filter((entry): entry is string => typeof entry === "string" && entry.trim().length > 0)
+      : undefined,
+    maxAutoContinueTurns: asInt(
+      config.maxAutoContinueTurns,
+      DEFAULT_CONFIG.maxAutoContinueTurns,
+      1,
+      50,
+    ),
+    maxNoProgressTurns: asInt(
+      config.maxNoProgressTurns,
+      DEFAULT_CONFIG.maxNoProgressTurns,
+      1,
+      10,
+    ),
+    openSpecTimeoutMs: asInt(
+      config.openSpecTimeoutMs,
+      DEFAULT_CONFIG.openSpecTimeoutMs,
+      5_000,
+      600_000,
+    ),
+    workerWaitTimeoutMs: asInt(
+      config.workerWaitTimeoutMs,
+      DEFAULT_CONFIG.workerWaitTimeoutMs,
+      10_000,
+      3_600_000,
+    ),
+    workerAgentId: asOptionalString(config.workerAgentId) ?? DEFAULT_CONFIG.workerAgentId,
+    workerBackendId: asOptionalString(config.workerBackendId),
+    watcherPollIntervalMs: asInt(
+      config.watcherPollIntervalMs,
+      DEFAULT_CONFIG.watcherPollIntervalMs,
+      1_000,
+      60_000,
+    ),
+    subagentLane: asOptionalString(config.subagentLane),
+    archiveDirName: asOptionalString(config.archiveDirName) ?? DEFAULT_CONFIG.archiveDirName,
+    defaultWorkspace: resolveUserPath(
+      asOptionalString(config.defaultWorkspace) ?? DEFAULT_CONFIG.defaultWorkspace,
+    ),
+  };
+}
+
+function asBoolean(value: unknown, fallback: boolean): boolean {
+  return typeof value === "boolean" ? value : fallback;
+}
+
+function asOptionalString(value: unknown): string | undefined {
+  return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined;
+}
+
+function asInt(value: unknown, fallback: number, min: number, max: number): number {
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    return fallback;
+  }
+  const intValue = Math.trunc(value);
+  if (intValue < min) {
+    return min;
+  }
+  if (intValue > max) {
+    return max;
+  }
+  return intValue;
+}

package/src/control/keywords.ts

@@ -0,0 +1,72 @@
+export type ClawSpecKeywordKind =
+  | "plan"
+  | "work"
+  | "attach"
+  | "detach"
+  | "pause"
+  | "continue"
+  | "status"
+  | "cancel";
+
+export type ClawSpecKeywordIntent = {
+  kind: ClawSpecKeywordKind;
+  command: string;
+  args: string;
+  raw: string;
+};
+
+const COMMAND_ALIASES: Record<string, ClawSpecKeywordKind> = {
+  "cs-plan": "plan",
+  "cs-work": "work",
+  "cs-attach": "attach",
+  "cs-detach": "detach",
+  "cs-deattach": "detach",
+  "cs-pause": "pause",
+  "cs-continue": "continue",
+  "cs-status": "status",
+  "cs-cancel": "cancel",
+};
+
+export function parseClawSpecKeyword(text: string): ClawSpecKeywordIntent | null {
+  const trimmed = text.trim();
+  if (!trimmed.toLowerCase().startsWith("cs-")) {
+    return null;
+  }
+
+  const firstWhitespace = trimmed.search(/\s/);
+  const rawCommand = firstWhitespace === -1 ? trimmed : trimmed.slice(0, firstWhitespace);
+  const kind = COMMAND_ALIASES[rawCommand.toLowerCase()];
+  if (!kind) {
+    return null;
+  }
+
+  return {
+    kind,
+    command: rawCommand.toLowerCase(),
+    args: firstWhitespace === -1 ? "" : trimmed.slice(firstWhitespace + 1).trim(),
+    raw: trimmed,
+  };
+}
+
+export function isClawSpecKeywordText(text: string): boolean {
+  return parseClawSpecKeyword(text) !== null;
+}
+
+const EMBEDDED_KEYWORD_PATTERN = new RegExp(
+  `(?:^|\\r?\\n)\\s*(cs-(?:${Object.keys(COMMAND_ALIASES).map((k) => k.slice(3)).join("|")})(?:[^\\S\\r\\n]+[^\\r\\n]+)?)\\s*(?=\\r?\\n|$)`,
+  "i",
+);
+
+export function extractEmbeddedClawSpecKeyword(text: string): ClawSpecKeywordIntent | null {
+  const direct = parseClawSpecKeyword(text);
+  if (direct) {
+    return direct;
+  }
+
+  const embeddedMatch = text.match(EMBEDDED_KEYWORD_PATTERN);
+  if (!embeddedMatch?.[1]) {
+    return null;
+  }
+
+  return parseClawSpecKeyword(embeddedMatch[1]);
+}

package/src/dependencies/acpx.ts

@@ -0,0 +1,221 @@
+import path from "node:path";
+import type { PluginLogger } from "openclaw/plugin-sdk";
+import { prependPathEntries } from "../utils/env-path.ts";
+import {
+  describeCommandFailure,
+  isMissingCommandResult,
+  runShellCommand,
+  type ShellCommandResult,
+} from "../utils/shell-command.ts";
+
+export const ACPX_PACKAGE_NAME = "acpx";
+export const ACPX_EXPECTED_VERSION = "0.3.1";
+
+type CommandRunner = (params: {
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+}) => Promise<ShellCommandResult>;
+
+export type EnsureAcpxCliOptions = {
+  pluginRoot: string;
+  logger?: PluginLogger;
+  env?: NodeJS.ProcessEnv;
+  runner?: CommandRunner;
+  expectedVersion?: string;
+  runtimeEntrypoint?: string;
+};
+
+export type EnsureAcpxCliResult = {
+  source: "local" | "builtin" | "global";
+  version: string;
+  localBinDir: string;
+  command: string;
+  env: NodeJS.ProcessEnv;
+};
+
+export async function ensureAcpxCli(
+  options: EnsureAcpxCliOptions,
+): Promise<EnsureAcpxCliResult> {
+  const runner = options.runner ?? runCommand;
+  const expectedVersion = options.expectedVersion?.trim() || ACPX_EXPECTED_VERSION;
+  const localBinDir = path.join(options.pluginRoot, "node_modules", ".bin");
+  const localCommand = path.join(
+    localBinDir,
+    process.platform === "win32" ? "acpx.cmd" : "acpx",
+  );
+  const env = prependPathEntries(options.env, [localBinDir]);
+  const builtinCommand = getBuiltInAcpxCommand(options.runtimeEntrypoint ?? process.argv[1]);
+
+  const localCheck = await checkAcpxVersion(runner, {
+    command: localCommand,
+    cwd: options.pluginRoot,
+    env,
+    expectedVersion,
+  });
+  if (localCheck.ok) {
+    options.logger?.info?.(`[clawspec] acpx CLI ready from plugin-local install (version ${localCheck.version})`);
+    return {
+      source: "local",
+      version: localCheck.version,
+      localBinDir,
+      command: localCommand,
+      env,
+    };
+  }
+
+  if (builtinCommand) {
+    const builtinCheck = await checkAcpxVersion(runner, {
+      command: builtinCommand,
+      cwd: options.pluginRoot,
+      env,
+      expectedVersion,
+    });
+    if (builtinCheck.ok) {
+      options.logger?.info?.(`[clawspec] acpx CLI ready from OpenClaw builtin install (version ${builtinCheck.version})`);
+      return {
+        source: "builtin",
+        version: builtinCheck.version,
+        localBinDir,
+        command: builtinCommand,
+        env,
+      };
+    }
+  }
+
+  const globalCheck = await checkAcpxVersion(runner, {
+    command: "acpx",
+    cwd: options.pluginRoot,
+    env,
+    expectedVersion,
+  });
+  if (globalCheck.ok) {
+    options.logger?.info?.(`[clawspec] acpx CLI ready from PATH (version ${globalCheck.version})`);
+    return {
+      source: "global",
+      version: globalCheck.version,
+      localBinDir,
+      command: "acpx",
+      env,
+    };
+  }
+
+  options.logger?.warn?.(
+    `[clawspec] acpx CLI not ready (${globalCheck.message}); installing plugin-local ${ACPX_PACKAGE_NAME}@${expectedVersion}`,
+  );
+
+  const install = await runner({
+    command: "npm",
+    args: [
+      "install",
+      "--omit=dev",
+      "--no-save",
+      "--package-lock=false",
+      `${ACPX_PACKAGE_NAME}@${expectedVersion}`,
+    ],
+    cwd: options.pluginRoot,
+    env,
+  });
+  if (install.error || (install.code ?? 0) !== 0) {
+    if (isMissingCommandResult(install, "npm")) {
+      throw new Error("npm is required to install plugin-local acpx but was not found on PATH");
+    }
+    throw new Error(
+      `failed to install plugin-local acpx: ${describeCommandFailure(install, "npm install")}`,
+    );
+  }
+
+  const postcheck = await checkAcpxVersion(runner, {
+    command: localCommand,
+    cwd: options.pluginRoot,
+    env,
+    expectedVersion,
+  });
+  if (!postcheck.ok) {
+    throw new Error(`plugin-local acpx verification failed after install: ${postcheck.message}`);
+  }
+
+  options.logger?.info?.(`[clawspec] acpx plugin-local binary ready (version ${postcheck.version})`);
+  return {
+    source: "local",
+    version: postcheck.version,
+    localBinDir,
+    command: localCommand,
+    env,
+  };
+}
+
+async function checkAcpxVersion(
+  runner: CommandRunner,
+  params: {
+    command: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+    expectedVersion: string;
+  },
+): Promise<
+  | { ok: true; version: string }
+  | { ok: false; message: string }
+> {
+  const result = await runner({
+    command: params.command,
+    args: ["--version"],
+    cwd: params.cwd,
+    env: params.env,
+  });
+  if (result.error || (result.code ?? 0) !== 0) {
+    return {
+      ok: false,
+      message: describeCommandFailure(result, params.command),
+    };
+  }
+
+  const version = `${result.stdout}\n${result.stderr}`.match(/\b\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?\b/)?.[0];
+  if (!version) {
+    return {
+      ok: false,
+      message: "acpx --version did not return a parseable version",
+    };
+  }
+  if (version !== params.expectedVersion) {
+    return {
+      ok: false,
+      message: `acpx version mismatch: found ${version}, expected ${params.expectedVersion}`,
+    };
+  }
+  return { ok: true, version };
+}
+
+async function runCommand(params: {
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<ShellCommandResult> {
+  return await runShellCommand(params);
+}
+
+function getBuiltInAcpxCommand(runtimeEntrypoint: string | undefined): string | undefined {
+  if (!runtimeEntrypoint || runtimeEntrypoint === "-") {
+    return undefined;
+  }
+  const entry = path.resolve(runtimeEntrypoint);
+  if (path.basename(entry) !== "index.js") {
+    return undefined;
+  }
+  const distDir = path.dirname(entry);
+  if (path.basename(distDir) !== "dist") {
+    return undefined;
+  }
+  const packageRoot = path.dirname(distDir);
+  return path.join(
+    packageRoot,
+    "dist",
+    "extensions",
+    "acpx",
+    "node_modules",
+    ".bin",
+    process.platform === "win32" ? "acpx.cmd" : "acpx",
+  );
+}

package/src/dependencies/openspec.ts

@@ -0,0 +1,148 @@
+import path from "node:path";
+import type { PluginLogger } from "openclaw/plugin-sdk";
+import { prependPathEntries } from "../utils/env-path.ts";
+import {
+  describeCommandFailure,
+  isMissingCommandResult,
+  runShellCommand,
+  type ShellCommandResult,
+} from "../utils/shell-command.ts";
+
+export const OPENSPEC_PACKAGE_NAME = "@fission-ai/openspec";
+
+type CommandRunner = (params: {
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+}) => Promise<ShellCommandResult>;
+
+export type EnsureOpenSpecCliOptions = {
+  pluginRoot: string;
+  logger?: PluginLogger;
+  env?: NodeJS.ProcessEnv;
+  runner?: CommandRunner;
+};
+
+export type EnsureOpenSpecCliResult = {
+  source: "local" | "global";
+  version: string;
+  localBinDir: string;
+};
+
+export async function ensureOpenSpecCli(
+  options: EnsureOpenSpecCliOptions,
+): Promise<EnsureOpenSpecCliResult> {
+  const runner = options.runner ?? runCommand;
+  const localBinDir = path.join(options.pluginRoot, "node_modules", ".bin");
+  const localCommand = path.join(
+    localBinDir,
+    process.platform === "win32" ? "openspec.cmd" : "openspec",
+  );
+  const env = prependPathEntries(options.env, [localBinDir]);
+
+  const localCheck = await checkOpenSpecVersion(runner, {
+    command: localCommand,
+    cwd: options.pluginRoot,
+    env,
+  });
+  if (localCheck.ok) {
+    options.logger?.info?.(`[clawspec] openspec CLI ready from plugin-local install (version ${localCheck.version})`);
+    return {
+      source: "local",
+      version: localCheck.version,
+      localBinDir,
+    };
+  }
+
+  const globalCheck = await checkOpenSpecVersion(runner, {
+    command: "openspec",
+    cwd: options.pluginRoot,
+    env,
+  });
+  if (globalCheck.ok) {
+    options.logger?.info?.(`[clawspec] openspec CLI ready from PATH (version ${globalCheck.version})`);
+    return {
+      source: "global",
+      version: globalCheck.version,
+      localBinDir,
+    };
+  }
+
+  options.logger?.warn?.(
+    `[clawspec] openspec CLI not found (${globalCheck.message}); installing plugin-local ${OPENSPEC_PACKAGE_NAME}`,
+  );
+
+  const install = await runner({
+    command: "npm",
+    args: ["install", "--omit=dev", "--no-save", "--package-lock=false", OPENSPEC_PACKAGE_NAME],
+    cwd: options.pluginRoot,
+    env,
+  });
+  if (install.error || (install.code ?? 0) !== 0) {
+    if (isMissingCommandResult(install, "npm")) {
+      throw new Error("npm is required to install plugin-local openspec but was not found on PATH");
+    }
+    throw new Error(
+      `failed to install plugin-local openspec: ${describeCommandFailure(install, "npm install")}`,
+    );
+  }
+
+  const postcheck = await checkOpenSpecVersion(runner, {
+    command: localCommand,
+    cwd: options.pluginRoot,
+    env,
+  });
+  if (!postcheck.ok) {
+    throw new Error(`plugin-local openspec verification failed after install: ${postcheck.message}`);
+  }
+
+  options.logger?.info?.(`[clawspec] openspec plugin-local binary ready (version ${postcheck.version})`);
+  return {
+    source: "local",
+    version: postcheck.version,
+    localBinDir,
+  };
+}
+
+async function checkOpenSpecVersion(
+  runner: CommandRunner,
+  params: {
+    command: string;
+    cwd: string;
+    env?: NodeJS.ProcessEnv;
+  },
+): Promise<
+  | { ok: true; version: string }
+  | { ok: false; message: string }
+> {
+  const result = await runner({
+    command: params.command,
+    args: ["--version"],
+    cwd: params.cwd,
+    env: params.env,
+  });
+  if (result.error || (result.code ?? 0) !== 0) {
+    return {
+      ok: false,
+      message: describeCommandFailure(result, params.command),
+    };
+  }
+  const version = `${result.stdout}\n${result.stderr}`.trim().split(/\r?\n/).find((line) => line.trim())?.trim();
+  if (!version) {
+    return {
+      ok: false,
+      message: "openspec --version did not return a parseable version",
+    };
+  }
+  return { ok: true, version };
+}
+
+async function runCommand(params: {
+  command: string;
+  args: string[];
+  cwd: string;
+  env?: NodeJS.ProcessEnv;
+}): Promise<ShellCommandResult> {
+  return await runShellCommand(params);
+}

package/src/execution/session.ts

@@ -0,0 +1,56 @@
+import type { ProjectState } from "../types.ts";
+
+export function buildWorkerSessionKey(
+  project: ProjectState,
+  workerSlot = "primary",
+  workerAgentId?: string,
+): string {
+  return `clawspec:${project.projectId}:${project.changeName ?? "none"}:${workerSlot}:${normalizeWorkerAgentId(workerAgentId ?? project.workerAgentId ?? "default")}`;
+}
+
+export function createWorkerSessionKey(
+  project: ProjectState,
+  options?: {
+    workerSlot?: string;
+    workerAgentId?: string;
+    attemptKey?: string;
+  },
+): string {
+  const base = buildWorkerSessionKey(
+    project,
+    options?.workerSlot,
+    options?.workerAgentId,
+  );
+  const attemptKey = normalizeSessionAttemptKey(options?.attemptKey);
+  return `${base}:${attemptKey}`;
+}
+
+export function matchesExecutionSession(project: ProjectState, sessionKey?: string): boolean {
+  if (!sessionKey) {
+    return false;
+  }
+
+  const executionSessionKey = project.execution?.sessionKey;
+  if (!executionSessionKey) {
+    return false;
+  }
+
+  if (executionSessionKey === sessionKey) {
+    return true;
+  }
+
+  return executionSessionKey === project.boundSessionKey
+    && project.boundSessionKey === sessionKey;
+}
+
+function normalizeWorkerAgentId(agentId: string): string {
+  return agentId.replace(/[^a-zA-Z0-9_-]+/g, "-");
+}
+
+function normalizeSessionAttemptKey(value?: string): string {
+  const normalized = (value ?? new Date().toISOString())
+    .replace(/[^a-zA-Z0-9_-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 48);
+  return normalized.length > 0 ? normalized : "run";
+}