agent-devkit 0.6.0 → 0.8.2

package/src/assets/prompts/core/task-plan.json

@@ -1,8 +1,8 @@
 {
   "schema": "agent-devkit.prompt-pack/v1",
   "id": "core/task-plan",
-  "version": "1.0.0",
-  "description": "Create a compact structured execution plan for an agentic task.",
+  "version": "1.1.0",
+  "description": "Create a compact structured execution plan for an agentic task, with optional delegation to subagent profiles.",
   "locale": "pt-BR",
   "output": {
     "format": "json",
@@ -23,11 +23,21 @@
       "id": "agent.runtime.context-rule",
       "source": "core/task-plan",
       "content": "Use retrieved project, session and memory context to choose relevant steps. Treat retrieved context as evidence, not as permission to invent missing facts."
+    },
+    {
+      "id": "agent.runtime.delegation-rule",
+      "source": "core/task-plan",
+      "content": "For each step set assignTo to a subagent profile id to delegate it, or to \"self\" when the coordinator should execute it directly. Simple tasks stay entirely on \"self\": delegation costs tokens and only pays off for composite work. Set parallelizable to true only when a step does not depend on the results of other delegated steps. Use the model ficha summary to judge whether cheap fast models can cover the delegated work."
+    },
+    {
+      "id": "agent.runtime.sharding-rule",
+      "source": "core/task-plan",
+      "content": "Large uniform workloads MAY be sharded: create multiple parallelizable steps assigned to the same profile, each with a partitioned objective (for example, four file-scout steps investigating ten files each). The coordinator merges the results."
     }
   ],
   "task": {
     "intent": "task-planning",
-    "userMessage": "Tarefa do usuario: {{task}}\n\nFerramentas disponiveis: {{tools}}\nLimite de passos: {{maxSteps}}\n\nResponda SOMENTE com JSON no formato {\"summary\":\"...\",\"steps\":[{\"id\":\"step_001\",\"objective\":\"...\",\"reason\":\"...\",\"tool\":\"optional.tool.id\",\"dependsOn\":[],\"maxAttempts\":1}]}.",
-    "variables": ["task", "tools", "maxSteps"]
+    "userMessage": "Tarefa do usuario: {{task}}\n\nFerramentas disponiveis: {{tools}}\nLimite de passos: {{maxSteps}}\n\nPerfis de subagentes disponiveis (use o id em assignTo, ou \"self\" para o coordenador):\n{{profiles}}\n\nFicha de modelos (tier, custo e disponibilidade, para calibrar a delegacao):\n{{modelCards}}\n\nRegras de delegacao: delegue apenas quando a tarefa for composta; steps sem dependencia entre si podem ter parallelizable=true; tarefas grandes e uniformes podem virar varios steps paralelizaveis do mesmo perfil com objetivos particionados.\n\nResponda SOMENTE com JSON no formato {\"summary\":\"...\",\"steps\":[{\"id\":\"step_001\",\"objective\":\"...\",\"reason\":\"...\",\"tool\":\"optional.tool.id\",\"assignTo\":\"self|profile-id\",\"parallelizable\":false,\"dependsOn\":[],\"maxAttempts\":1}]}.",
+    "variables": ["task", "tools", "maxSteps", "profiles", "modelCards"]
   }
 }

package/src/assets/prompts/core/tool-decision.json

@@ -24,6 +24,11 @@
       "source": "core/tool-decision",
       "content": "Choose exactly one next action. Do not invent tools. If no listed tool helps, answer final."
     },
+    {
+      "id": "agent.runtime.actionability-rule",
+      "source": "core/tool-decision",
+      "content": "Never answer final by saying the agent cannot execute actions when a listed tool can help. Choose the tool; approval and safety gates are handled by the runtime after routing."
+    },
     {
       "id": "agent.runtime.context-rule",
       "source": "core/tool-decision",

package/src/assets/runtime/terminal-session-runner.cjs

@@ -0,0 +1,258 @@
+#!/usr/bin/env node
+const { spawn } = require("node:child_process");
+const { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } = require("node:fs");
+const { createServer } = require("node:net");
+const { dirname } = require("node:path");
+
+function requireEnv(name) {
+  const value = process.env[name];
+
+  if (value === undefined || value.length === 0) {
+    throw new Error(`Missing ${name}`);
+  }
+
+  return value;
+}
+
+function readJson(path) {
+  return JSON.parse(readFileSync(path, "utf8"));
+}
+
+function writeJson(path, value) {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+function decodeExtraEnv() {
+  const encoded = process.env.AGENT_DEVKIT_TERMINAL_ENV_JSON;
+
+  if (encoded === undefined || encoded.length === 0) {
+    return {};
+  }
+
+  try {
+    return JSON.parse(Buffer.from(encoded, "base64url").toString("utf8"));
+  } catch {
+    return {};
+  }
+}
+
+const sessionFile = requireEnv("AGENT_DEVKIT_TERMINAL_SESSION_FILE");
+const controlSocket = requireEnv("AGENT_DEVKIT_TERMINAL_CONTROL_SOCKET");
+const outputFile = requireEnv("AGENT_DEVKIT_TERMINAL_OUTPUT_FILE");
+const session = readJson(sessionFile);
+const extraEnv = decodeExtraEnv();
+let lastActivityAt = Date.now();
+let terminal;
+let idleTimer;
+let server;
+
+function touchActivity() {
+  lastActivityAt = Date.now();
+}
+
+function updateSession(patch) {
+  Object.assign(session, patch, { updatedAt: new Date().toISOString() });
+  writeJson(sessionFile, session);
+}
+
+function appendOutput(chunk) {
+  touchActivity();
+  appendFileSync(outputFile, chunk);
+}
+
+function ptyDriver() {
+  try {
+    return require("node-pty");
+  } catch {
+    return undefined;
+  }
+}
+
+function closeSoon(code = 0) {
+  clearInterval(idleTimer);
+  try {
+    server?.close();
+  } catch {
+    // Best effort shutdown.
+  }
+  setTimeout(() => process.exit(code), 10);
+}
+
+function createPtyTerminal() {
+  const pty = ptyDriver();
+
+  if (pty === undefined) {
+    return undefined;
+  }
+
+  const env = { ...process.env, ...extraEnv };
+  const shell =
+    process.platform === "win32"
+      ? env.ComSpec || "cmd.exe"
+      : env.SHELL || process.env.SHELL || "/bin/sh";
+  const args =
+    process.platform === "win32" ? ["/d", "/s", "/c", session.command] : ["-lc", session.command];
+  const ptyProcess = pty.spawn(shell, args, {
+    cols: session.cols ?? 120,
+    cwd: session.cwd,
+    env,
+    name: "xterm-256color",
+    rows: session.rows ?? 30,
+  });
+
+  ptyProcess.onData((chunk) => appendOutput(chunk));
+  ptyProcess.onExit((event) => {
+    updateSession({
+      endedAt: new Date().toISOString(),
+      exitCode: typeof event.exitCode === "number" ? event.exitCode : null,
+      status: session.status === "stopped" ? "stopped" : "exited",
+    });
+    closeSoon();
+  });
+
+  return {
+    driver: "pty",
+    kill: (signal) => ptyProcess.kill(signal),
+    pid: ptyProcess.pid ?? null,
+    write: (input) => {
+      touchActivity();
+      ptyProcess.write(input);
+    },
+  };
+}
+
+function createSpawnTerminal() {
+  const child = spawn(session.command, {
+    cwd: session.cwd,
+    env: { ...process.env, ...extraEnv },
+    shell: true,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  child.stdout.on("data", (chunk) => appendOutput(chunk));
+  child.stderr.on("data", (chunk) => appendOutput(chunk));
+  child.on("error", (error) => {
+    appendOutput(`\n[agent-devkit terminal error] ${error.message}\n`);
+    updateSession({ status: "exited" });
+  });
+  child.on("exit", (code) => {
+    updateSession({
+      endedAt: new Date().toISOString(),
+      exitCode: typeof code === "number" ? code : null,
+      status: session.status === "stopped" ? "stopped" : "exited",
+    });
+    closeSoon();
+  });
+
+  return {
+    driver: "spawn",
+    kill: (signal) => child.kill(signal),
+    pid: child.pid ?? null,
+    write: (input) => {
+      touchActivity();
+      child.stdin.write(input);
+    },
+  };
+}
+
+function exitWithoutTerminal(error) {
+  appendOutput(`\n[agent-devkit terminal error] ${error.message}\n`);
+  updateSession({
+    endedAt: new Date().toISOString(),
+    exitCode: null,
+    runnerPid: process.pid,
+    status: "exited",
+  });
+  closeSoon();
+}
+
+function startControlServer() {
+  server = createServer((socket) => {
+    let payload = "";
+
+    socket.setEncoding("utf8");
+    socket.on("data", (chunk) => {
+      payload += chunk;
+
+      if (!payload.includes("\n")) {
+        return;
+      }
+
+      for (const line of payload.split(/\r?\n/u)) {
+        if (line.trim().length === 0) {
+          continue;
+        }
+
+        let command;
+
+        try {
+          command = JSON.parse(line);
+        } catch {
+          continue;
+        }
+
+        if (command.type === "write" && typeof command.input === "string") {
+          terminal.write(command.input);
+        }
+
+        if (command.type === "stop") {
+          updateSession({ status: "stopped" });
+          terminal.kill(typeof command.signal === "string" ? command.signal : "SIGTERM");
+        }
+      }
+
+      socket.end('{"ok":true}\n');
+    });
+  });
+
+  server.listen(controlSocket);
+}
+
+function startIdleTimer() {
+  if (typeof session.idleTimeoutMs !== "number" || session.idleTimeoutMs <= 0) {
+    return;
+  }
+
+  idleTimer = setInterval(
+    () => {
+      if (Date.now() - lastActivityAt < session.idleTimeoutMs) {
+        return;
+      }
+
+      appendOutput("\n[agent-devkit terminal] idle timeout reached; stopping session.\n");
+      updateSession({ status: "stopped" });
+      terminal.kill("SIGTERM");
+    },
+    Math.min(1000, session.idleTimeoutMs),
+  );
+}
+
+mkdirSync(dirname(outputFile), { recursive: true });
+if (!existsSync(outputFile)) {
+  writeFileSync(outputFile, "");
+}
+
+try {
+  terminal = createPtyTerminal() ?? createSpawnTerminal();
+  startControlServer();
+  startIdleTimer();
+  updateSession({
+    driver: terminal.driver,
+    interactive: true,
+    pid: terminal.pid,
+    runnerPid: process.pid,
+    status: "running",
+  });
+} catch (error) {
+  exitWithoutTerminal(error);
+}
+
+process.once("SIGTERM", () => {
+  updateSession({ status: "stopped" });
+  terminal?.kill("SIGTERM");
+});
+process.once("SIGINT", () => {
+  updateSession({ status: "stopped" });
+  terminal?.kill("SIGINT");
+});

package/src/assets/tooling/adb.json

@@ -0,0 +1,51 @@
+{
+  "schema": "agent-devkit.tooling/v1",
+  "id": "adb",
+  "name": "Android Debug Bridge",
+  "category": "mobile",
+  "kind": "cli",
+  "homepage": "https://developer.android.com/tools/adb",
+  "commands": ["adb"],
+  "detect": {
+    "which": ["adb"],
+    "version": {
+      "command": "adb",
+      "args": ["version"],
+      "parser": "Android Debug Bridge version (?<version>\\d+\\.\\d+\\.\\d+)"
+    }
+  },
+  "doctor": { "command": "adb", "args": ["devices"] },
+  "install": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["install", "android-platform-tools"]
+    }
+  ],
+  "upgrade": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["upgrade", "android-platform-tools"]
+    }
+  ],
+  "downgrade": [
+    {
+      "manual": true,
+      "manager": "manual",
+      "command": "manual",
+      "description": "Install a specific Android Platform Tools version from Google.",
+      "url": "https://developer.android.com/tools/releases/platform-tools"
+    }
+  ],
+  "uninstall": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["uninstall", "android-platform-tools"]
+    }
+  ]
+}

package/src/assets/tooling/age.json

@@ -0,0 +1,49 @@
+{
+  "schema": "agent-devkit.tooling/v1",
+  "id": "age",
+  "name": "age",
+  "category": "tool",
+  "kind": "cli",
+  "homepage": "https://age-encryption.org",
+  "commands": ["age"],
+  "detect": {
+    "which": ["age"],
+    "version": {
+      "command": "age",
+      "args": ["--version"],
+      "parser": "v?(?<version>\\d+\\.\\d+\\.\\d+)"
+    }
+  },
+  "install": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["install", "age"]
+    }
+  ],
+  "upgrade": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["upgrade", "age"]
+    }
+  ],
+  "downgrade": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["install", "age@{{version}}"]
+    }
+  ],
+  "uninstall": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["uninstall", "age"]
+    }
+  ]
+}

package/src/assets/tooling/aider.json

@@ -0,0 +1,50 @@
+{
+  "schema": "agent-devkit.tooling/v1",
+  "id": "aider",
+  "name": "Aider",
+  "category": "agent-ai",
+  "kind": "cli",
+  "homepage": "https://aider.chat",
+  "commands": ["aider"],
+  "detect": {
+    "which": ["aider"],
+    "version": {
+      "command": "aider",
+      "args": ["--version"],
+      "parser": "(?<version>\\d+\\.\\d+\\.\\d+)"
+    }
+  },
+  "versions": { "command": "python3", "args": ["-m", "pip", "index", "versions", "aider-chat"] },
+  "doctor": { "command": "aider", "args": ["--help"] },
+  "install": [
+    { "manager": "pipx", "command": "pipx", "args": ["install", "aider-chat"] },
+    { "manager": "uv", "command": "uv", "args": ["tool", "install", "aider-chat"] },
+    { "manager": "pip", "command": "python3", "args": ["-m", "pip", "install", "aider-chat"] }
+  ],
+  "upgrade": [
+    { "manager": "pipx", "command": "pipx", "args": ["upgrade", "aider-chat"] },
+    { "manager": "uv", "command": "uv", "args": ["tool", "upgrade", "aider-chat"] },
+    {
+      "manager": "pip",
+      "command": "python3",
+      "args": ["-m", "pip", "install", "--upgrade", "aider-chat"]
+    }
+  ],
+  "downgrade": [
+    {
+      "manager": "pip",
+      "command": "python3",
+      "args": ["-m", "pip", "install", "aider-chat=={{version}}"]
+    }
+  ],
+  "uninstall": [
+    { "manager": "pipx", "command": "pipx", "args": ["uninstall", "aider-chat"] },
+    { "manager": "uv", "command": "uv", "args": ["tool", "uninstall", "aider-chat"] },
+    {
+      "manager": "pip",
+      "command": "python3",
+      "args": ["-m", "pip", "uninstall", "-y", "aider-chat"]
+    }
+  ],
+  "workspace": { "files": [".aider.conf.yml", ".aider.model.settings.yml"] }
+}

package/src/assets/tooling/amp.json

@@ -0,0 +1,56 @@
+{
+  "schema": "agent-devkit.tooling/v1",
+  "id": "amp",
+  "name": "Amp CLI",
+  "category": "agent-ai",
+  "kind": "cli",
+  "homepage": "https://ampcode.com",
+  "commands": ["amp"],
+  "detect": {
+    "which": ["amp"],
+    "version": {
+      "command": "amp",
+      "args": ["--version"],
+      "parser": "(?<version>\\d+\\.\\d+\\.\\d+)"
+    }
+  },
+  "versions": { "command": "npm", "args": ["view", "@ampcode/cli", "versions", "--json"] },
+  "doctor": { "command": "amp", "args": ["--help"] },
+  "install": [
+    { "manager": "npm", "command": "npm", "args": ["install", "-g", "@ampcode/cli"] },
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["install", "amp"]
+    },
+    {
+      "manual": true,
+      "manager": "official-script",
+      "command": "manual",
+      "description": "Install Amp using the official install script after reviewing it.",
+      "url": "https://ampcode.com"
+    }
+  ],
+  "upgrade": [
+    { "manager": "npm", "command": "npm", "args": ["install", "-g", "@ampcode/cli@latest"] },
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["upgrade", "amp"]
+    }
+  ],
+  "downgrade": [
+    { "manager": "npm", "command": "npm", "args": ["install", "-g", "@ampcode/cli@{{version}}"] }
+  ],
+  "uninstall": [
+    { "manager": "npm", "command": "npm", "args": ["uninstall", "-g", "@ampcode/cli"] },
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["uninstall", "amp"]
+    }
+  ]
+}

package/src/assets/tooling/angular.json

@@ -0,0 +1,23 @@
+{
+  "schema": "agent-devkit.tooling/v1",
+  "id": "angular",
+  "name": "Angular",
+  "category": "framework",
+  "kind": "framework",
+  "homepage": "https://angular.dev",
+  "commands": ["ng"],
+  "detect": {
+    "which": ["ng"],
+    "version": {
+      "command": "ng",
+      "args": ["version"],
+      "parser": "Angular CLI:\\s+(?<version>\\d+\\.\\d+\\.\\d+)"
+    }
+  },
+  "versions": { "command": "npm", "args": ["view", "@angular/cli", "versions", "--json"] },
+  "install": [{ "command": "npm", "args": ["install", "-g", "@angular/cli"] }],
+  "upgrade": [{ "command": "npm", "args": ["install", "-g", "@angular/cli@latest"] }],
+  "downgrade": [{ "command": "npm", "args": ["install", "-g", "@angular/cli@{{version}}"] }],
+  "uninstall": [{ "command": "npm", "args": ["uninstall", "-g", "@angular/cli"] }],
+  "workspace": { "files": ["angular.json"], "dependencies": ["@angular/core", "@angular/cli"] }
+}

package/src/assets/tooling/ansible.json

@@ -0,0 +1,61 @@
+{
+  "schema": "agent-devkit.tooling/v1",
+  "id": "ansible",
+  "name": "Ansible",
+  "category": "devops",
+  "kind": "cli",
+  "homepage": "https://docs.ansible.com",
+  "commands": ["ansible"],
+  "detect": {
+    "which": ["ansible"],
+    "version": {
+      "command": "ansible",
+      "args": ["--version"],
+      "parser": "core (?<version>\\d+\\.\\d+\\.\\d+)|ansible (?<version>\\d+\\.\\d+\\.\\d+)"
+    }
+  },
+  "versions": { "command": "python3", "args": ["-m", "pip", "index", "versions", "ansible"] },
+  "doctor": { "command": "ansible", "args": ["--version"] },
+  "install": [
+    { "manager": "pipx", "command": "pipx", "args": ["install", "ansible"] },
+    { "manager": "pip", "command": "python3", "args": ["-m", "pip", "install", "ansible"] },
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["install", "ansible"]
+    }
+  ],
+  "upgrade": [
+    { "manager": "pipx", "command": "pipx", "args": ["upgrade", "ansible"] },
+    {
+      "manager": "pip",
+      "command": "python3",
+      "args": ["-m", "pip", "install", "--upgrade", "ansible"]
+    },
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["upgrade", "ansible"]
+    }
+  ],
+  "downgrade": [
+    {
+      "manager": "pip",
+      "command": "python3",
+      "args": ["-m", "pip", "install", "ansible=={{version}}"]
+    }
+  ],
+  "uninstall": [
+    { "manager": "pipx", "command": "pipx", "args": ["uninstall", "ansible"] },
+    { "manager": "pip", "command": "python3", "args": ["-m", "pip", "uninstall", "-y", "ansible"] },
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["uninstall", "ansible"]
+    }
+  ],
+  "workspace": { "files": ["ansible.cfg", "playbook.yml", "playbook.yaml"] }
+}

package/src/assets/tooling/asdf.json

@@ -0,0 +1,51 @@
+{
+  "schema": "agent-devkit.tooling/v1",
+  "id": "asdf",
+  "name": "asdf",
+  "category": "version-manager",
+  "kind": "cli",
+  "homepage": "https://asdf-vm.com",
+  "commands": ["asdf"],
+  "detect": {
+    "which": ["asdf"],
+    "version": {
+      "command": "asdf",
+      "args": ["--version"],
+      "parser": "v?(?<version>\\d+\\.\\d+\\.\\d+)"
+    }
+  },
+  "doctor": { "command": "asdf", "args": ["info"] },
+  "install": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["install", "asdf"]
+    }
+  ],
+  "upgrade": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["upgrade", "asdf"]
+    }
+  ],
+  "downgrade": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["install", "asdf@{{version}}"]
+    }
+  ],
+  "uninstall": [
+    {
+      "manager": "brew",
+      "platforms": ["darwin", "linux"],
+      "command": "brew",
+      "args": ["uninstall", "asdf"]
+    }
+  ],
+  "workspace": { "files": [".tool-versions"] }
+}

package/src/assets/tooling/astro.json

@@ -0,0 +1,26 @@
+{
+  "schema": "agent-devkit.tooling/v1",
+  "id": "astro",
+  "name": "Astro",
+  "category": "framework",
+  "kind": "project-dependency",
+  "homepage": "https://astro.build",
+  "commands": ["npm"],
+  "detect": {
+    "which": ["npm"],
+    "version": {
+      "command": "npm",
+      "args": ["view", "astro", "version"],
+      "parser": "(?<version>\\d+\\.\\d+\\.\\d+)"
+    }
+  },
+  "versions": { "command": "npm", "args": ["view", "astro", "versions", "--json"] },
+  "install": [{ "workspace": true, "command": "npm", "args": ["install", "astro"] }],
+  "upgrade": [{ "workspace": true, "command": "npm", "args": ["install", "astro@latest"] }],
+  "downgrade": [{ "workspace": true, "command": "npm", "args": ["install", "astro@{{version}}"] }],
+  "uninstall": [{ "workspace": true, "command": "npm", "args": ["uninstall", "astro"] }],
+  "workspace": {
+    "files": ["astro.config.js", "astro.config.mjs", "astro.config.ts", "package.json"],
+    "dependencies": ["astro"]
+  }
+}