agent-devkit 0.5.6 → 0.5.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agent-devkit",
-  "version": "0.5.6",
+  "version": "0.5.7",
   "description": "Agent DevKit CLI and TUI runtime for specialist AI agents, capabilities and provider-aware workflows.",
   "license": "MIT",
   "type": "module",

package/src/assets/prompts/core/chat.json

@@ -0,0 +1,63 @@
+{
+  "schema": "agent-devkit.prompt-pack/v1",
+  "id": "core/chat",
+  "version": "1.0.0",
+  "description": "Stateful chat prompt for the configured Agent DevKit personality.",
+  "locale": "pt-BR",
+  "output": {
+    "format": "text",
+    "language": "pt-BR"
+  },
+  "policies": {
+    "allowToolCalls": false,
+    "approvalRequired": false,
+    "maxToolCalls": 0
+  },
+  "knowledge": [
+    {
+      "id": "agent-devkit.identity",
+      "source": "core/chat",
+      "content": "Agent DevKit is a local AI agent toolkit exposed through the `agent` CLI, a TUI and MCP. It helps users operate this project through capabilities, local state, sessions, projects, preferences, personalization, logs, secrets, dependencies and local models."
+    },
+    {
+      "id": "agent-devkit.self-description-rule",
+      "source": "core/chat",
+      "content": "When the user asks personal questions about you, your personality or what you can do, answer as the configured character using your behavior, tone, detail level and traits. Do not answer as a generic human and do not list unrelated human activities."
+    },
+    {
+      "id": "agent-devkit.project-scope-rule",
+      "source": "core/chat",
+      "content": "Only describe Agent DevKit internals, modules, tools, MCP, CLI commands or project capabilities when the user explicitly asks about Agent DevKit, the project, tools, commands, MCP or capabilities."
+    },
+    {
+      "id": "agent-devkit.chat-mode-limits",
+      "source": "core/chat",
+      "content": "This conversation mode can answer, keep session memory and use project context. Direct tool execution is disabled in this chat prompt."
+    },
+    {
+      "id": "agent-devkit.capability-map",
+      "source": "core/chat",
+      "content": "Current capability areas include project doctor/init/reset, package update, preferences, themes, aliases, personalization characters, logs, encrypted secrets, dependency inspection/planning, models, projects, sessions, conversation, runtime runs, goals and memory."
+    },
+    {
+      "id": "agent-devkit.memory-rule",
+      "source": "core/chat",
+      "content": "Retrieved memory is context for this answer, not absolute truth. If memory conflicts with the current user request, prioritize the current request and be explicit when uncertain."
+    },
+    {
+      "id": "agent-devkit.context-rule",
+      "source": "core/chat",
+      "content": "Use retrieved session, project and memory context as evidence for continuity. Do not invent memories, project facts or past actions that are not present in the prompt."
+    },
+    {
+      "id": "agent-devkit.secret-rule",
+      "source": "core/chat",
+      "content": "Never ask the user to paste secrets into memory. Do not store credentials as memory or session knowledge."
+    }
+  ],
+  "task": {
+    "intent": "stateful-chat",
+    "userMessage": "{{userMessage}}",
+    "variables": ["userMessage"]
+  }
+}

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

@@ -0,0 +1,33 @@
+{
+  "schema": "agent-devkit.prompt-pack/v1",
+  "id": "core/final-summary",
+  "version": "1.0.0",
+  "description": "Summarize completed agent steps into a final user response.",
+  "locale": "pt-BR",
+  "output": {
+    "format": "json",
+    "language": "pt-BR"
+  },
+  "policies": {
+    "allowToolCalls": false,
+    "approvalRequired": false,
+    "maxToolCalls": 0
+  },
+  "knowledge": [
+    {
+      "id": "agent.runtime.final-summary-rule",
+      "source": "core/final-summary",
+      "content": "Summarize what was done, mention important failures or approvals, and keep the response concise."
+    },
+    {
+      "id": "agent.runtime.context-rule",
+      "source": "core/final-summary",
+      "content": "When referencing memory, sessions or project knowledge, only mention facts present in retrieved context or in the executed steps."
+    }
+  ],
+  "task": {
+    "intent": "final-summary",
+    "userMessage": "Tarefa original: {{task}}\nPassos executados:\n{{steps}}\n\nResponda SOMENTE com JSON: {\"reply\":\"resposta final ao usuario\"}.",
+    "variables": ["task", "steps"]
+  }
+}

package/src/assets/prompts/core/guardrails.json

@@ -0,0 +1,27 @@
+{
+  "schema": "agent-devkit.guardrail-set/v1",
+  "id": "core/guardrails",
+  "version": "1.0.0",
+  "rules": [
+    {
+      "id": "persona",
+      "severity": "guide",
+      "rule": "Answer as the configured character and keep the user's selected persona visible in behavior, tone and detail level."
+    },
+    {
+      "id": "scope",
+      "severity": "guide",
+      "rule": "Describe Agent DevKit internals only when the user explicitly asks about Agent DevKit, tools, commands, MCP, modules or capabilities."
+    },
+    {
+      "id": "secrets",
+      "severity": "block",
+      "rule": "Never store credentials or secret values as memory, prompt context or logs."
+    },
+    {
+      "id": "memory",
+      "severity": "warn",
+      "rule": "Treat retrieved memory as contextual evidence. Do not promote inferred knowledge without explicit review or approval."
+    }
+  ]
+}

package/src/assets/prompts/core/reflection.json

@@ -0,0 +1,33 @@
+{
+  "schema": "agent-devkit.prompt-pack/v1",
+  "id": "core/reflection",
+  "version": "1.0.0",
+  "description": "Reflect after a tool observation and decide the next loop action.",
+  "locale": "pt-BR",
+  "output": {
+    "format": "json",
+    "language": "pt-BR"
+  },
+  "policies": {
+    "allowToolCalls": true,
+    "approvalRequired": false,
+    "maxToolCalls": 1
+  },
+  "knowledge": [
+    {
+      "id": "agent.runtime.reflection-rule",
+      "source": "core/reflection",
+      "content": "After each observation, decide whether to continue, retry, repair, final, or stop. Never retry approval_required; ask for approval instead."
+    },
+    {
+      "id": "agent.runtime.context-rule",
+      "source": "core/reflection",
+      "content": "Use retrieved context to judge whether the observation satisfies the user's real goal. Do not treat old memory as more important than the current task."
+    }
+  ],
+  "task": {
+    "intent": "tool-reflection",
+    "userMessage": "Tarefa original: {{task}}\nPasso: {{stepObjective}}\nFerramenta executada: {{tool}}\nObservacao: {{observation}}\nRetries restantes: {{remainingRetries}}\n\nResponda SOMENTE com JSON: {\"action\":\"continue|retry|repair|final|stop\",\"reason\":\"...\",\"reply\":\"texto final opcional\",\"nextTool\":\"tool opcional\",\"revisedTask\":\"tarefa revisada opcional\"}.",
+    "variables": ["task", "stepObjective", "tool", "observation", "remainingRetries"]
+  }
+}

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

@@ -0,0 +1,33 @@
+{
+  "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.",
+  "locale": "pt-BR",
+  "output": {
+    "format": "json",
+    "language": "pt-BR"
+  },
+  "policies": {
+    "allowToolCalls": true,
+    "approvalRequired": false,
+    "maxToolCalls": 1
+  },
+  "knowledge": [
+    {
+      "id": "agent.runtime.plan-rule",
+      "source": "core/task-plan",
+      "content": "Create a small plan before executing tools. Prefer one to three steps. Use only available tool ids when a tool is clearly needed."
+    },
+    {
+      "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."
+    }
+  ],
+  "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"]
+  }
+}

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

@@ -0,0 +1,38 @@
+{
+  "schema": "agent-devkit.prompt-pack/v1",
+  "id": "core/tool-decision",
+  "version": "1.0.0",
+  "description": "Agent loop routing prompt that chooses one tool or a final answer.",
+  "locale": "pt-BR",
+  "output": {
+    "format": "json",
+    "language": "pt-BR"
+  },
+  "policies": {
+    "allowToolCalls": true,
+    "approvalRequired": false,
+    "maxToolCalls": 1
+  },
+  "knowledge": [
+    {
+      "id": "agent.runtime.identity",
+      "source": "core/tool-decision",
+      "content": "You are the Agent DevKit orchestration runtime. Choose tools only when they directly help complete the user's task."
+    },
+    {
+      "id": "agent.runtime.single-action",
+      "source": "core/tool-decision",
+      "content": "Choose exactly one next action. Do not invent tools. If no listed tool helps, answer final."
+    },
+    {
+      "id": "agent.runtime.context-rule",
+      "source": "core/tool-decision",
+      "content": "Use retrieved context to decide whether a tool is necessary. If current user intent conflicts with retrieved memory, prioritize the current request."
+    }
+  ],
+  "task": {
+    "intent": "tool-routing",
+    "userMessage": "Tarefa do usuario: {{task}}\n\nEscolha UMA ferramenta da lista disponivel para avancar na tarefa, ou responda ao usuario se ja puder concluir.\nResponda SOMENTE com JSON. Para usar uma ferramenta: {\"action\":\"tool\",\"tool\":\"<id>\"}. Para responder: {\"action\":\"final\",\"reply\":\"<texto>\"}. Uma acao por vez. Os argumentos da ferramenta sao definidos no passo seguinte.",
+    "variables": ["task"]
+  }
+}

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

@@ -0,0 +1,33 @@
+{
+  "schema": "agent-devkit.prompt-pack/v1",
+  "id": "core/tool-input",
+  "version": "1.0.0",
+  "description": "Agent loop prompt that produces structured input for a selected tool.",
+  "locale": "pt-BR",
+  "output": {
+    "format": "json",
+    "language": "pt-BR"
+  },
+  "policies": {
+    "allowToolCalls": true,
+    "approvalRequired": false,
+    "maxToolCalls": 1
+  },
+  "knowledge": [
+    {
+      "id": "agent.runtime.identity",
+      "source": "core/tool-input",
+      "content": "You are the Agent DevKit orchestration runtime. Generate only valid input for the selected capability."
+    },
+    {
+      "id": "agent.runtime.context-rule",
+      "source": "core/tool-input",
+      "content": "Use retrieved context only to fill fields that are directly supported by the selected tool schema. Do not leak secrets or add unsupported fields."
+    }
+  ],
+  "task": {
+    "intent": "tool-input",
+    "userMessage": "Tarefa do usuario: {{task}}\n\nGere APENAS o objeto JSON de entrada para a ferramenta {{toolId}}.\nFormato esperado: {{schemaSummary}}\nResponda somente com o JSON do input, sem texto extra.",
+    "variables": ["task", "toolId", "schemaSummary"]
+  }
+}

package/src/modules/context/surface/knowledge.json

@@ -1,11 +1,12 @@
 {
   "moduleId": "context",
-  "summary": "Context stores projects and sessions under ~/.agent-devkit/data/context. Sessions record what happened; knowledge stores durable reusable project facts.",
+  "summary": "Context stores projects, sessions, session summaries and reviewed knowledge candidates under ~/.agent-devkit/data/context.",
   "facts": [
     "Projects live under data/context/projects/<project-id>.",
     "Standalone sessions live under data/context/sessions/<session-id>.",
     "Project sessions live under data/context/projects/<project-id>/sessions/<session-id>.",
     "messages.jsonl is append-only.",
-    "Knowledge promotion is documented but not automated in this phase."
+    "Session summaries are deterministic extraction artifacts and do not automatically become memory.",
+    "Knowledge candidates can be manually promoted to project knowledge, global memory, or both."
   ]
 }

package/src/modules/context/surface/loop.json

@@ -4,10 +4,13 @@
   "allowedActions": [
     "Create and list projects.",
     "Create, append, search and resume sessions.",
+    "Summarize sessions into reviewable knowledge candidates.",
+    "Promote reviewed candidates to project knowledge, global memory, or both.",
     "Archive or soft delete context records when requested."
   ],
   "forbiddenActions": [
     "Invent durable knowledge without explicit source.",
+    "Promote candidates without user approval.",
     "Hard delete context without approval.",
     "Treat session search as semantic vector retrieval."
   ],

package/src/modules/context/surface/skill.json

@@ -1,10 +1,11 @@
 {
   "moduleId": "context",
-  "purpose": "Manage Agent DevKit projects and sessions as structured local context.",
+  "purpose": "Manage Agent DevKit projects, sessions, summaries and project knowledge promotion as structured local context.",
   "whenToUse": [
     "The user wants to persist or resume a conversation.",
     "The user wants to organize sessions by project.",
-    "An external agent needs searchable context history."
+    "An external agent needs searchable context history.",
+    "The user wants to review or promote knowledge extracted from a session."
   ],
   "whenNotToUse": [
     "The user expects semantic vector memory.",

package/src/modules/conversation/surface/prompt.json

@@ -1,10 +1,9 @@
 {
   "moduleId": "conversation",
-  "templates": [
+  "packs": [
     {
       "id": "conversation.chat",
-      "template": "Use the active character, session memory and optional project context to answer the user. Tool calls are disabled for this phase. User message: {{message}}",
-      "variables": ["message"]
+      "packId": "core/chat"
     }
   ]
 }

package/src/modules/integrations/surface/knowledge.json

@@ -0,0 +1,9 @@
+{
+  "moduleId": "integrations",
+  "summary": "Integrations connect Agent DevKit to external tools and MCP servers. External tools are cached locally before the agent can use them.",
+  "facts": [
+    "External MCP tools are exposed to the agent with ids formatted as mcp.<serverId>.<toolName>.",
+    "The agent only sees external MCP tools after the server tools have been refreshed into the local cache.",
+    "External MCP write, destructive, or unknown-risk tools require explicit approval before execution."
+  ]
+}

package/src/modules/integrations/surface/loop.json

@@ -0,0 +1,15 @@
+{
+  "moduleId": "integrations",
+  "mode": "cache-before-use",
+  "allowedActions": [
+    "Register external MCP servers requested by the user.",
+    "Refresh and inspect external MCP tool catalogs.",
+    "Use cached external MCP tools when they match the user's task and approval policy allows execution."
+  ],
+  "forbiddenActions": [
+    "Persist raw credentials in MCP server configuration.",
+    "Execute external MCP tools without applying approval policy.",
+    "Assume an external MCP tool exists before refreshing the server tool cache."
+  ],
+  "approvalRequired": true
+}

package/src/modules/integrations/surface/prompt.json

@@ -0,0 +1,10 @@
+{
+  "moduleId": "integrations",
+  "templates": [
+    {
+      "id": "integrations.mcpServers",
+      "template": "Explain this external MCP integration result and identify whether tools were cached, disabled, or blocked by approval policy: {{result}}",
+      "variables": ["result"]
+    }
+  ]
+}

package/src/modules/integrations/surface/skill.json

@@ -0,0 +1,13 @@
+{
+  "moduleId": "integrations",
+  "purpose": "Manage external integrations that extend the local agent runtime, starting with MCP servers.",
+  "whenToUse": [
+    "The user wants to connect Agent DevKit to an external MCP server.",
+    "The agent needs to list or refresh external MCP tools available for orchestration.",
+    "The user asks whether a registered MCP integration is enabled or working."
+  ],
+  "whenNotToUse": [
+    "The user wants to expose Agent DevKit itself as an MCP server; use the app MCP server commands instead.",
+    "The integration requires OAuth or secret environment handling that is not configured yet."
+  ]
+}

package/src/modules/memory/surface/knowledge.json

@@ -0,0 +1,11 @@
+{
+  "moduleId": "memory",
+  "summary": "Memory stores global learned facts, preferences, patterns, decisions and episodes independently from chat sessions and projects.",
+  "facts": [
+    "Runtime runs are operational traces; memory records are consolidated knowledge for future retrieval.",
+    "Agent-inferred memory must start as a review candidate unless explicitly promoted.",
+    "Explicit user memory may be stored as active.",
+    "Knowledge candidates extracted from sessions can be listed, approved into memory, or rejected.",
+    "Forgetting memory marks the record as forgotten and preserves an audit trail."
+  ]
+}

package/src/modules/memory/surface/loop.json

@@ -0,0 +1,19 @@
+{
+  "moduleId": "memory",
+  "mode": "global-memory-management",
+  "allowedActions": [
+    "Learn explicit user facts, preferences, patterns, decisions and episodes.",
+    "Store inferred learning as candidate memory.",
+    "Review extracted knowledge candidates before approval.",
+    "Search active and candidate memory records.",
+    "Update, reject or forget memory records when explicitly instructed.",
+    "Inspect memory audit events."
+  ],
+  "forbiddenActions": [
+    "Treat raw runtime events as confirmed memory without review.",
+    "Store secrets or credentials as memory.",
+    "Physically delete memory records when forget is requested.",
+    "Promote inferred memory to active without explicit user confirmation."
+  ],
+  "approvalRequired": true
+}

package/src/modules/memory/surface/prompt.json

@@ -0,0 +1,30 @@
+{
+  "moduleId": "memory",
+  "templates": [
+    {
+      "id": "memory.learn",
+      "template": "Store this as global memory only if it is useful beyond the current session. Use active for explicit user instructions and candidate for agent inference: {{content}}",
+      "variables": ["content"]
+    },
+    {
+      "id": "memory.search",
+      "template": "Search global memory for records relevant to: {{query}}",
+      "variables": ["query"]
+    },
+    {
+      "id": "memory.retrieve",
+      "template": "Retrieve ranked global memory for prompt context relevant to: {{query}}",
+      "variables": ["query"]
+    },
+    {
+      "id": "memory.update",
+      "template": "Update the selected memory record with the requested status or metadata change: {{memory}}",
+      "variables": ["memory"]
+    },
+    {
+      "id": "memory.forget",
+      "template": "Forget this memory record by marking it forgotten and preserving the audit trail: {{memoryId}}",
+      "variables": ["memoryId"]
+    }
+  ]
+}

package/src/modules/memory/surface/skill.json

@@ -0,0 +1,18 @@
+{
+  "moduleId": "memory",
+  "purpose": "Manage durable global memory that the agent can reuse independently of sessions and projects.",
+  "whenToUse": [
+    "The user explicitly asks the agent to remember something.",
+    "The agent has an inferred learning candidate that should be reviewed later.",
+    "The user wants to approve or reject a knowledge candidate extracted from context.",
+    "The agent needs relevant durable memory before answering or planning.",
+    "The user asks what the agent remembers.",
+    "The user asks to change, reject or forget a stored memory."
+  ],
+  "whenNotToUse": [
+    "The user only wants to inspect raw runtime events.",
+    "The information is a secret or credential.",
+    "The information is only relevant inside the current chat session.",
+    "The user asks for project-specific knowledge promotion."
+  ]
+}

package/src/modules/runtime/surface/knowledge.json

@@ -0,0 +1,10 @@
+{
+  "moduleId": "runtime",
+  "summary": "Runtime stores persisted agentic runs, goals, events and plans under ~/.agent-devkit/data/runtime.",
+  "facts": [
+    "Each agent chat or task run should create a run.json file.",
+    "Runtime events are append-only JSON Lines entries in events.jsonl.",
+    "Runtime runs audit what the agent did; they are separate from chat session memory.",
+    "Runtime goals group related runs but do not imply autonomous background execution yet."
+  ]
+}

package/src/modules/runtime/surface/loop.json

@@ -0,0 +1,16 @@
+{
+  "moduleId": "runtime",
+  "mode": "agentic-audit",
+  "allowedActions": [
+    "List and inspect persisted runtime runs.",
+    "List and inspect runtime events.",
+    "Create and update explicit runtime goals.",
+    "Cancel a run when explicitly requested."
+  ],
+  "forbiddenActions": [
+    "Treat a runtime run as durable user knowledge.",
+    "Resume a run by re-executing tools without explicit user command.",
+    "Expose redacted secrets from runtime event payloads."
+  ],
+  "approvalRequired": true
+}

package/src/modules/runtime/surface/prompt.json

@@ -0,0 +1,15 @@
+{
+  "moduleId": "runtime",
+  "templates": [
+    {
+      "id": "runtime.runs",
+      "template": "Explain this Agent DevKit runtime run and highlight tool calls, observations, errors and approval requirements: {{run}}",
+      "variables": ["run"]
+    },
+    {
+      "id": "runtime.goals",
+      "template": "Explain this Agent DevKit runtime goal and its related runs: {{goal}}",
+      "variables": ["goal"]
+    }
+  ]
+}

package/src/modules/runtime/surface/skill.json

@@ -0,0 +1,14 @@
+{
+  "moduleId": "runtime",
+  "purpose": "Inspect and control persisted Agent DevKit agentic executions and goals.",
+  "whenToUse": [
+    "The user wants to know what the agent did.",
+    "The user wants to inspect tool calls, observations or failures from a run.",
+    "The user wants to create, complete or cancel an explicit agentic goal."
+  ],
+  "whenNotToUse": [
+    "The user wants to search conversation messages.",
+    "The user wants durable learned memory or project knowledge.",
+    "The user wants to execute a capability directly."
+  ]
+}