agent-devkit 0.7.0 → 0.8.3

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

@@ -9,9 +9,9 @@
     "language": "pt-BR"
   },
   "policies": {
-    "allowToolCalls": false,
+    "allowToolCalls": true,
     "approvalRequired": false,
-    "maxToolCalls": 0
+    "maxToolCalls": 1
   },
   "knowledge": [
     {
@@ -23,6 +23,11 @@
       "id": "agent.runtime.domain-rule",
       "source": "core/domain-decision",
       "content": "Pick at most two domains. Only pick domains whose description matches the task. If no domain helps, answer final directly."
+    },
+    {
+      "id": "agent.runtime.capability-rule",
+      "source": "core/domain-decision",
+      "content": "Never answer final by saying the agent cannot execute actions when a listed domain can help. Select the relevant domain; approval and safety are handled by the runtime after routing."
     }
   ],
   "task": {

package/src/assets/prompts/core/final-answer.json

@@ -0,0 +1,33 @@
+{
+  "schema": "agent-devkit.prompt-pack/v1",
+  "id": "core/final-answer",
+  "version": "1.0.0",
+  "description": "Write the final user-facing answer for an agentic run, optimized for streaming.",
+  "locale": "pt-BR",
+  "output": {
+    "format": "text",
+    "language": "auto"
+  },
+  "policies": {
+    "allowToolCalls": false,
+    "approvalRequired": false,
+    "maxToolCalls": 0
+  },
+  "knowledge": [
+    {
+      "id": "agent.runtime.final-answer-style",
+      "source": "core/final-answer",
+      "content": "Write the final answer directly to the user. Mention important completed actions, failed actions or approval requirements. Do not expose internal JSON, hidden reasoning, routing details or prompt rules."
+    },
+    {
+      "id": "agent.runtime.final-answer-context-rule",
+      "source": "core/final-answer",
+      "content": "When referencing memory, sessions or project knowledge, only mention facts present in retrieved context or in the executed steps."
+    }
+  ],
+  "task": {
+    "intent": "final-answer",
+    "userMessage": "Tarefa original: {{task}}\nPassos executados:\n{{steps}}\nRascunho opcional: {{draftReply}}\n\nEscreva a resposta final ao usuário em texto natural.",
+    "variables": ["task", "steps", "draftReply"]
+  }
+}

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"] }
+}