agent-devkit 0.3.4 → 0.5.6

package/dist/main.js

@@ -8,7 +8,7 @@ import React from "react";
 // package.json
 var package_default = {
   name: "agent-devkit",
-  version: "0.3.4",
+  version: "0.5.6",
   description: "Agent DevKit CLI and TUI runtime for specialist AI agents, capabilities and provider-aware workflows.",
   license: "MIT",
   type: "module",
@@ -50,7 +50,7 @@ var package_default = {
     "release:verify": "node scripts/verify-release-alignment.mjs",
     test: "npm run test:architecture && npm run test:infra && npm run test:app && npm run test:modules",
     "test:app": "vitest run src/app/cli/commands src/app/mcp src/app/tui src/package.test.ts",
-    "test:architecture": "vitest run src/architecture.test.ts src/modules/capability_registry.test.ts src/modules/capability_tool_runtime.test.ts src/modules/modules.registry.test.ts",
+    "test:architecture": "vitest run src/agent src/architecture.test.ts src/modules/capability_registry.test.ts src/modules/capability_tool_runtime.test.ts src/modules/modules.registry.test.ts",
     "test:infra": "vitest run src/infra",
     "test:module": "tsx scripts/test-modules.ts",
     "test:modules": "tsx scripts/test-modules.ts",
@@ -3385,6 +3385,80 @@ function createEnvironmentSurface() {
 // src/app/cli/toolRuntime.ts
 import { homedir as homedir11 } from "os";
 
+// src/infra/helpers/tool_schema_summary.ts
+var MAX_VARIANTS = 12;
+var MAX_PROPS = 10;
+var MAX_ENUM = 6;
+function asRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) ? value : void 0;
+}
+function propHint(name, schema, required) {
+  const suffix = required ? "" : "?";
+  const enumValues = Array.isArray(schema?.enum) ? schema?.enum : void 0;
+  if (enumValues !== void 0 && enumValues.length > 0) {
+    const shown = enumValues.slice(0, MAX_ENUM).map(String).join("|");
+    const more = enumValues.length > MAX_ENUM ? "|..." : "";
+    return `${name}[${shown}${more}]${suffix}`;
+  }
+  return `${name}${suffix}`;
+}
+function detectDiscriminator(variants) {
+  const first = asRecord(variants[0]?.properties);
+  if (first === void 0) {
+    return void 0;
+  }
+  for (const name of Object.keys(first)) {
+    const isDiscriminator = variants.every((variant) => {
+      const property = asRecord(asRecord(variant.properties)?.[name]);
+      return property !== void 0 && (typeof property.const === "string" || Array.isArray(property.enum));
+    });
+    if (isDiscriminator) {
+      return name;
+    }
+  }
+  return void 0;
+}
+function variantSummary(variant, discriminator) {
+  const props = asRecord(variant.properties);
+  if (props === void 0) {
+    return void 0;
+  }
+  const required = new Set(Array.isArray(variant.required) ? variant.required : []);
+  const discriminatorSchema = asRecord(props[discriminator]);
+  const label = typeof discriminatorSchema?.const === "string" ? discriminatorSchema.const : Array.isArray(discriminatorSchema?.enum) ? String((discriminatorSchema?.enum)[0]) : void 0;
+  if (label === void 0) {
+    return void 0;
+  }
+  const params = Object.keys(props).filter((name) => name !== discriminator).slice(0, MAX_PROPS).map((name) => propHint(name, asRecord(props[name]), required.has(name)));
+  const paramText = params.length > 0 ? `(${params.join(", ")})` : "";
+  return `${label}${paramText}`;
+}
+function summarizeToolSchema(schema) {
+  const union = Array.isArray(schema.oneOf) ? schema.oneOf : Array.isArray(schema.anyOf) ? schema.anyOf : void 0;
+  if (union !== void 0) {
+    const variants = union.map(asRecord).filter((variant) => variant !== void 0);
+    const discriminator = detectDiscriminator(variants) ?? "action";
+    const summaries = variants.slice(0, MAX_VARIANTS).map((variant) => variantSummary(variant, discriminator)).filter((summary) => summary !== void 0);
+    if (summaries.length === 0) {
+      return "";
+    }
+    const more2 = variants.length > MAX_VARIANTS ? " | ..." : "";
+    return `${discriminator} = ${summaries.join(" | ")}${more2}`;
+  }
+  const props = asRecord(schema.properties);
+  if (props === void 0) {
+    return "";
+  }
+  const required = new Set(Array.isArray(schema.required) ? schema.required : []);
+  const names = Object.keys(props);
+  const fields = names.slice(0, MAX_PROPS).map((name) => propHint(name, asRecord(props[name]), required.has(name)));
+  if (fields.length === 0) {
+    return "";
+  }
+  const more = names.length > MAX_PROPS ? ", ..." : "";
+  return `fields: ${fields.join(", ")}${more}`;
+}
+
 // src/infra/models/model_store.ts
 import { createHash } from "crypto";
 import { once } from "events";
@@ -3724,11 +3798,14 @@ function systemPromptFrom(prompt) {
     );
   }
   if (prompt.tools.length > 0) {
-    lines.push(
-      "",
-      "Available tools:",
-      ...prompt.tools.map((tool) => `- ${tool.id} (${tool.risk}): ${tool.description}`)
-    );
+    lines.push("", "Available tools:");
+    for (const tool of prompt.tools) {
+      lines.push(`- ${tool.id} (${tool.risk}): ${tool.description}`);
+      const schema = tool.inputSchema === void 0 ? "" : summarizeToolSchema(tool.inputSchema);
+      if (schema.length > 0) {
+        lines.push(`  input: ${schema}`);
+      }
+    }
   }
   lines.push(
     "",
@@ -3743,7 +3820,7 @@ function systemPromptFrom(prompt) {
     );
   }
   lines.push(`Reply in ${prompt.output.language}.`);
-  const history = prompt.messages.filter((message) => message.role === "user" || message.role === "assistant").slice(0, -1).map((message) => `${message.role === "user" ? "User" : agent.name}: ${message.content}`);
+  const history = prompt.messages.filter((message) => message.role === "user" || message.role === "assistant").slice(0, -1).map((message) => `${message.role}: ${message.content}`);
   if (history.length > 0) {
     lines.push("", "Conversation so far:", ...history);
   }
@@ -3878,7 +3955,9 @@ var LocalLlamaBrainProvider = class {
       return cached;
     }
     if (this.#llama === void 0) {
-      this.#llama = await llama.getLlama();
+      this.#llama = await llama.getLlama({
+        logLevel: llama.LlamaLogLevel?.error ?? llama.LlamaLogLevel?.fatal
+      });
     }
     const model = await this.#llama.loadModel({ modelPath });
     this.#models.set(modelPath, model);
@@ -3888,7 +3967,7 @@ var LocalLlamaBrainProvider = class {
 
 // src/infra/brain/mock_provider.ts
 function reply(request) {
-  const text2 = `${request.prompt.agent.name}: Entendi. Vou responder no contexto da sess\xE3o atual: "${request.prompt.task.userMessage}".`;
+  const text2 = `Entendi. Vou responder no contexto da sess\xE3o atual: "${request.prompt.task.userMessage}".`;
   const inputTokens = request.prompt.messages.map((message) => message.content.split(/\s+/g).filter(Boolean).length).reduce((total, count) => total + count, 0);
   const outputTokens = text2.split(/\s+/g).filter(Boolean).length;
   return {
@@ -3913,8 +3992,11 @@ var MockBrainProvider = class {
     onToken(response.text);
     return Result.ok(response);
   }
-  async generateStructured(request, _jsonSchema) {
-    const raw = JSON.stringify({ action: "final", reply: reply(request).text });
+  async generateStructured(request, jsonSchema) {
+    const properties = typeof jsonSchema.properties === "object" && jsonSchema.properties !== null && !Array.isArray(jsonSchema.properties) ? jsonSchema.properties : {};
+    const isAgentRouteSchema = "action" in properties && "tool" in properties;
+    const text2 = isAgentRouteSchema ? "Mock brain ativo. Instale ou configure um modelo local para executar roteamento agentic real." : reply(request).text;
+    const raw = JSON.stringify({ action: "final", reply: text2 });
     return Result.ok({ json: JSON.parse(raw), raw });
   }
 };
@@ -5676,37 +5758,19 @@ var conversationChatCapabilityConfig = defineCapabilityConfig({
   kind: "brain-assisted",
   risk: "writes-global-state"
 });
-function normalizeQuestion(value) {
-  return value.normalize("NFD").replaceAll(new RegExp("\\p{Diacritic}", "gu"), "").toLowerCase().replaceAll(/[^\p{Letter}\p{Number}\s]/gu, " ").replaceAll(/\s+/g, " ").trim();
-}
-function isSelfDescriptionQuestion(message) {
-  const normalized = normalizeQuestion(message);
-  return normalized === "o que voce pode fazer" || normalized === "o que voce faz" || normalized === "quais sao suas capacidades" || normalized === "quais suas capacidades" || normalized === "what can you do" || normalized === "what do you do";
+function stripLeadingAgentPrefixes(text2, agentName) {
+  const escaped = agentName.replaceAll(/[.*+?^${}()|[\]\\]/g, "\\$&");
+  const prefixPattern = new RegExp(`^(?:\\s*${escaped}\\s*:\\s*)+`, "iu");
+  return text2.replace(prefixPattern, "").trim();
 }
-function countPromptTokens(request) {
-  return request.prompt.messages.map((message) => message.content.split(/\s+/g).filter(Boolean).length).reduce((total, count) => total + count, 0);
-}
-function selfDescriptionResponse(request) {
-  if (!isSelfDescriptionQuestion(request.prompt.task.userMessage)) {
-    return void 0;
-  }
-  const { agent } = request.prompt;
-  const traits = agent.traits.length === 0 ? "sem tracos extras configurados" : agent.traits.join(", ");
-  const text2 = `${agent.name}: Eu posso conversar com voce mantendo o contexto da sessao, ajudar a raciocinar, organizar ideias, analisar informacoes e responder no meu estilo configurado. Minha postura e ${agent.behavior}, meu tom e ${agent.tone}, meu nivel de detalhe e ${agent.detailLevel}, e meus tracos atuais sao: ${traits}.`;
-  const inputTokens = countPromptTokens(request);
+function responseWithText(response, text2) {
   const outputTokens = text2.split(/\s+/g).filter(Boolean).length;
-  return {
-    finishReason: "stop",
-    model: "self-description",
-    provider: "system",
-    schema: "agent-devkit.brain-response/v1",
-    text: text2,
-    usage: {
-      inputTokens,
-      outputTokens,
-      totalTokens: inputTokens + outputTokens
-    }
+  const usage = response.usage === void 0 ? void 0 : {
+    ...response.usage,
+    outputTokens,
+    totalTokens: response.usage.inputTokens === void 0 ? response.usage.totalTokens : response.usage.inputTokens + outputTokens
   };
+  return { ...response, text: text2, usage };
 }
 var ConversationChatService = class extends BaseCapabilityService {
   inputSchema = ConversationChatOptionsSchema;
@@ -5751,32 +5815,32 @@ var ConversationChatService = class extends BaseCapabilityService {
       return Result.fail(prepared.unwrapError());
     }
     const request = {
-      options: parsed.data.brain ?? { provider: "local" },
+      options: { provider: "local", ...parsed.data.brain, role: "chat" },
       prompt: prepared.unwrap().prompt,
       schema: "agent-devkit.brain-request/v1"
     };
-    const selfDescription = selfDescriptionResponse(request);
-    const brain = selfDescription === void 0 ? onToken !== void 0 && this.#brainProvider.generateStream !== void 0 ? await this.#brainProvider.generateStream(request, onToken) : await this.#brainProvider.generate(request) : Result.ok(selfDescription);
-    if (selfDescription !== void 0) {
-      onToken?.(selfDescription.text);
-    }
+    const brain = onToken !== void 0 && this.#brainProvider.generateStream !== void 0 ? await this.#brainProvider.generateStream(request, onToken) : await this.#brainProvider.generate(request);
     if (brain.isErr()) {
       return Result.fail(brain.unwrapError());
     }
+    const normalizedBrain = responseWithText(
+      brain.unwrap(),
+      stripLeadingAgentPrefixes(brain.unwrap().text, prepared.unwrap().prompt.agent.name)
+    );
     const messages = await this.#repository.appendAssistantMessage(
       prepared.unwrap().sessionId,
-      brain.unwrap().text
+      normalizedBrain.text
     );
     if (messages.isErr()) {
       return Result.fail(messages.unwrapError());
     }
     const result = this.outputSchema.safeParse({
       action: "send",
-      brain: brain.unwrap(),
+      brain: normalizedBrain,
       messages: messages.unwrap(),
       projectId: prepared.unwrap().projectId,
       prompt: prepared.unwrap().prompt,
-      reply: brain.unwrap().text,
+      reply: normalizedBrain.text,
       sessionId: prepared.unwrap().sessionId
     });
     return result.success ? Result.ok(result.data) : Result.fail(ErrorCodes.InvalidInput);
@@ -8140,6 +8204,37 @@ function registerLogsCommand(program2, options) {
   );
 }
 
+// src/modules/module_knowledge_catalog.ts
+function createModuleSurfaceKnowledge() {
+  let cache;
+  return {
+    async all() {
+      if (cache !== void 0) {
+        return cache;
+      }
+      const modules = [];
+      for (const definition of agentModuleDefinitions) {
+        const surface = definition.surface();
+        const [knowledge, skill, loop] = await Promise.all([
+          surface.knowledge(),
+          surface.skill(),
+          surface.loop()
+        ]);
+        modules.push({
+          facts: knowledge.isOk() ? knowledge.unwrap().facts : [],
+          forbiddenActions: loop.isOk() ? loop.unwrap().forbiddenActions : [],
+          moduleId: definition.id,
+          summary: knowledge.isOk() ? knowledge.unwrap().summary : "",
+          whenNotToUse: skill.isOk() ? skill.unwrap().whenNotToUse : [],
+          whenToUse: skill.isOk() ? skill.unwrap().whenToUse : []
+        });
+      }
+      cache = modules;
+      return modules;
+    }
+  };
+}
+
 // src/app/mcp/mcp_http_transport.ts
 import { createServer } from "http";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
@@ -8150,29 +8245,139 @@ import { join as join16 } from "path";
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
   CallToolRequestSchema,
-  ListToolsRequestSchema
+  ListResourcesRequestSchema,
+  ListToolsRequestSchema,
+  ReadResourceRequestSchema
 } from "@modelcontextprotocol/sdk/types.js";
 
-// src/infra/agent/agent_runtime.ts
+// src/agent/agent.brain.ts
 import { z as z23 } from "zod";
-var AgentDecisionSchema = z23.discriminatedUnion("action", [
-  z23.object({ action: z23.literal("tool"), input: z23.unknown(), tool: z23.string().min(1) }),
+var AgentRouteSchema = z23.discriminatedUnion("action", [
+  z23.object({ action: z23.literal("tool"), tool: z23.string().min(1) }),
   z23.object({ action: z23.literal("final"), reply: z23.string() })
 ]);
-var agentDecisionJsonSchema = {
+var agentRouteJsonSchema = {
   type: "object",
   properties: {
     action: { type: "string", enum: ["tool", "final"] },
-    input: { type: "object" },
     reply: { type: "string" },
     tool: { type: "string" }
   },
   required: ["action"]
 };
+var agentPersona = {
+  behavior: "balanced",
+  characterId: "agent",
+  detailLevel: "concise",
+  name: "Agent",
+  tone: "direct",
+  traits: []
+};
+var identityKnowledge = {
+  content: "You are the Agent DevKit orchestration runtime. Choose tools only when they directly help complete the user's task.",
+  id: "agent.runtime.identity"
+};
+function maxToolCallsFor(tools) {
+  return Math.max(1, tools.length);
+}
+function moduleGuidance(knowledge) {
+  const entries = [];
+  for (const module of knowledge) {
+    const parts = [];
+    if (module.summary.length > 0) {
+      parts.push(module.summary);
+    }
+    if (module.whenToUse.length > 0) {
+      parts.push(`Use when: ${module.whenToUse.join(" ")}`);
+    }
+    if (module.whenNotToUse.length > 0) {
+      parts.push(`Avoid when: ${module.whenNotToUse.join(" ")}`);
+    }
+    if (module.forbiddenActions.length > 0) {
+      parts.push(`Never: ${module.forbiddenActions.join(" ")}`);
+    }
+    if (parts.length === 0) {
+      continue;
+    }
+    entries.push({
+      content: `${module.moduleId} \u2014 ${parts.join(" ")}`,
+      id: `module.${module.moduleId}`
+    });
+  }
+  return entries;
+}
+function buildToolDecisionPrompt(input) {
+  const instruction = [
+    `Tarefa do usu\xE1rio: ${input.task}`,
+    "",
+    "Escolha UMA ferramenta da lista dispon\xEDvel para avan\xE7ar na tarefa, ou responda ao usu\xE1rio se j\xE1 puder concluir.",
+    'Responda SOMENTE com JSON. Para usar uma ferramenta: {"action":"tool","tool":"<id>"}. Para responder: {"action":"final","reply":"<texto>"}. Uma a\xE7\xE3o por vez. Os argumentos da ferramenta s\xE3o definidos no passo seguinte.'
+  ].join("\n");
+  return AgentPromptSchema.parse({
+    agent: input.agent ?? agentPersona,
+    context: {
+      knowledge: [identityKnowledge, ...moduleGuidance(input.knowledge ?? [])]
+    },
+    locale: "pt-BR",
+    messages: input.transcript,
+    output: { format: "json", language: "pt-BR" },
+    policies: {
+      allowToolCalls: true,
+      approvalRequired: false,
+      maxToolCalls: maxToolCallsFor(input.tools)
+    },
+    schema: "agent-devkit.prompt/v1",
+    task: { userMessage: instruction },
+    tools: input.tools.map((tool) => ({
+      description: tool.description,
+      id: tool.id,
+      inputSchema: tool.inputSchema,
+      risk: tool.risk
+    }))
+  });
+}
+function buildToolInputPrompt(input) {
+  const schema = summarizeToolSchema(input.tool.inputSchema);
+  const instruction = [
+    `Tarefa do usu\xE1rio: ${input.task}`,
+    "",
+    `Gere APENAS o objeto JSON de entrada para a ferramenta ${input.tool.id}.`,
+    schema.length > 0 ? `Formato esperado: ${schema}` : "",
+    "Responda somente com o JSON do input, sem texto extra."
+  ].filter((line) => line.length > 0).join("\n");
+  return AgentPromptSchema.parse({
+    agent: input.agent ?? agentPersona,
+    context: { knowledge: [identityKnowledge] },
+    locale: "pt-BR",
+    messages: input.transcript,
+    output: { format: "json", language: "pt-BR" },
+    policies: { allowToolCalls: true, approvalRequired: false, maxToolCalls: 1 },
+    schema: "agent-devkit.prompt/v1",
+    task: { userMessage: instruction },
+    tools: [
+      {
+        description: input.tool.description,
+        id: input.tool.id,
+        inputSchema: input.tool.inputSchema,
+        risk: input.tool.risk
+      }
+    ]
+  });
+}
+
+// src/agent/agent.policy.ts
+function isToolApproved(tool, input) {
+  if (input.approvedTools !== void 0) {
+    return input.approvedTools.includes(tool);
+  }
+  return input.approved === true;
+}
+
+// src/agent/agent.loop.ts
 function summarize(value) {
   const text2 = typeof value === "string" ? value : JSON.stringify(value ?? "");
   const compact2 = text2.replaceAll(/\s+/g, " ").trim();
-  return compact2.length > 240 ? `${compact2.slice(0, 240)}\u2026` : compact2;
+  return compact2.length > 240 ? `${compact2.slice(0, 240)}...` : compact2;
 }
 function observationSummary(result) {
   if (result.status === "succeeded") {
@@ -8180,11 +8385,15 @@ function observationSummary(result) {
   }
   return `${result.status}${result.error === void 0 ? "" : `: ${result.error.message}`}`;
 }
-var AgentRuntime = class {
+var AgentToolLoop = class {
+  #agent;
   #brain;
+  #knowledge;
   #tools;
   constructor(options) {
+    this.#agent = options.agent;
     this.#brain = options.brainProvider;
+    this.#knowledge = options.knowledge;
     this.#tools = options.toolRuntime;
   }
   async run(input) {
@@ -8199,32 +8408,51 @@ var AgentRuntime = class {
       role: message.role
     }));
     const tools = this.#tools.listTools();
+    const knowledge = await this.#knowledgeForTools(tools.map((tool) => tool.moduleId));
     for (let step = 0; step < maxSteps; step += 1) {
-      const prompt = this.#buildPrompt(input.task, transcript, tools);
-      const request = {
-        options: { provider: "local", role: "agent" },
-        prompt,
-        schema: "agent-devkit.brain-request/v1"
-      };
-      const structured = await generateStructured(request, agentDecisionJsonSchema);
-      if (structured.isErr()) {
-        return Result.fail(structured.unwrapError());
+      const routePrompt = buildToolDecisionPrompt({
+        agent: input.agent ?? this.#agent,
+        knowledge,
+        task: input.task,
+        tools,
+        transcript
+      });
+      const routed = await generateStructured(
+        {
+          options: { provider: "local", role: "agent" },
+          prompt: routePrompt,
+          schema: "agent-devkit.brain-request/v1"
+        },
+        agentRouteJsonSchema
+      );
+      if (routed.isErr()) {
+        return Result.fail(routed.unwrapError());
       }
-      const decision = AgentDecisionSchema.safeParse(structured.unwrap().json);
-      if (!decision.success) {
-        return Result.ok({ reply: structured.unwrap().raw.trim(), steps });
+      const route = AgentRouteSchema.safeParse(routed.unwrap().json);
+      if (!route.success) {
+        return Result.fail(ErrorCodes.InvalidInput);
       }
-      if (decision.data.action === "final") {
-        input.onEvent?.({ reply: decision.data.reply, type: "final" });
-        return Result.ok({ reply: decision.data.reply, steps });
+      if (route.data.action === "final") {
+        input.onEvent?.({ reply: route.data.reply, type: "final" });
+        return Result.ok({ mode: "task", reply: route.data.reply, steps });
       }
-      const tool = decision.data.tool;
+      const tool = route.data.tool;
       input.onEvent?.({ tool, type: "tool" });
+      const toolInput = await this.#resolveToolInput(
+        generateStructured,
+        tool,
+        input.task,
+        transcript,
+        input.agent ?? this.#agent
+      );
+      if (toolInput.isErr()) {
+        return Result.fail(toolInput.unwrapError());
+      }
       const execution = await this.#tools.execute({
-        approved: this.#isApproved(tool, input),
+        approved: isToolApproved(tool, input),
         capabilityId: tool,
-        input: decision.data.input,
-        interface: "agent",
+        input: toolInput.unwrap(),
+        interface: input.interface ?? "agent",
         requestedBy: "agent.run"
       });
       const ok = execution.status === "succeeded";
@@ -8234,64 +8462,114 @@ var AgentRuntime = class {
       transcript.push({ content: `Observation from ${tool}: ${summary}`, role: "tool" });
       if (execution.status === "approval_required") {
         return Result.ok({
+          mode: "task",
           reply: `A ferramenta ${tool} requer aprova\xE7\xE3o expl\xEDcita. Reexecute autorizando para continuar.`,
           steps
         });
       }
     }
     return Result.ok({
+      mode: "task",
       reply: "Limite de passos do agente atingido sem uma resposta final.",
       steps
     });
   }
-  #isApproved(tool, input) {
-    if (input.approvedTools !== void 0) {
-      return input.approvedTools.includes(tool);
+  async #knowledgeForTools(moduleIds) {
+    if (this.#knowledge === void 0) {
+      return [];
     }
-    return input.approved === true;
+    const present = new Set(moduleIds);
+    const all = await this.#knowledge.all();
+    return all.filter((module) => present.has(module.moduleId));
   }
-  #buildPrompt(task, transcript, tools) {
-    const toolList = tools.map((tool) => `- ${tool.id} (${tool.risk}): ${tool.description}`).join("\n");
-    const instruction = [
-      `Tarefa do usu\xE1rio: ${task}`,
-      "",
-      "Ferramentas dispon\xEDveis:",
-      toolList,
-      "",
-      'Responda SOMENTE com JSON. Para usar uma ferramenta: {"action":"tool","tool":"<id>","input":{...}}. Para responder ao usu\xE1rio: {"action":"final","reply":"<texto>"}. Uma a\xE7\xE3o por vez.'
-    ].join("\n");
-    return AgentPromptSchema.parse({
-      agent: {
-        behavior: "balanced",
-        characterId: "agent",
-        detailLevel: "concise",
-        name: "Agent",
-        tone: "direct",
-        traits: []
-      },
-      context: { knowledge: [] },
-      locale: "pt-BR",
-      messages: transcript,
-      output: { format: "json", language: "pt-BR" },
-      policies: {
-        allowToolCalls: true,
-        approvalRequired: false,
-        maxToolCalls: maxToolCallsFor(tools)
-      },
-      schema: "agent-devkit.prompt/v1",
-      task: { userMessage: instruction },
-      tools: tools.map((tool) => ({
-        description: tool.description,
-        id: tool.id,
-        inputSchema: tool.inputSchema,
-        risk: tool.risk
-      }))
-    });
+  async #resolveToolInput(generateStructured, tool, task, transcript, agent) {
+    const descriptor = this.#tools.getTool(tool);
+    if (descriptor.isErr()) {
+      return Result.fail(descriptor.unwrapError());
+    }
+    const request = {
+      options: { provider: "local", role: "agent" },
+      prompt: buildToolInputPrompt({ agent, task, tool: descriptor.unwrap(), transcript }),
+      schema: "agent-devkit.brain-request/v1"
+    };
+    const produced = await generateStructured(request, descriptor.unwrap().inputSchema);
+    if (produced.isErr()) {
+      return Result.fail(produced.unwrapError());
+    }
+    return Result.ok(produced.unwrap().json ?? {});
   }
 };
-function maxToolCallsFor(tools) {
-  return Math.max(1, tools.length);
+
+// src/agent/agent.runtime.ts
+function textInput(input) {
+  return (input.message ?? input.task ?? "").trim();
+}
+function resolveMode(input) {
+  if (input.mode === "chat" || input.mode === "task") {
+    return input.mode;
+  }
+  if (input.message !== void 0) {
+    return "chat";
+  }
+  return "task";
+}
+function chatInput(input, message) {
+  return {
+    characterId: input.characterId,
+    includeHistory: input.includeHistory,
+    interface: input.interface ?? "cli",
+    message,
+    projectId: input.projectId,
+    sessionId: input.sessionId
+  };
 }
+var AgentRuntime = class {
+  #agent;
+  #conversation;
+  #toolLoop;
+  constructor(options) {
+    this.#agent = options.agent;
+    this.#conversation = options.conversation;
+    this.#toolLoop = new AgentToolLoop({
+      agent: options.agent,
+      brainProvider: options.brainProvider,
+      knowledge: options.knowledge,
+      toolRuntime: options.toolRuntime
+    });
+  }
+  async run(input) {
+    const message = textInput(input);
+    if (message.length === 0) {
+      return Result.fail(ErrorCodes.InvalidInput);
+    }
+    const mode = resolveMode(input);
+    if (mode === "chat") {
+      return this.#runChat(input, message);
+    }
+    return this.#toolLoop.run({ ...input, agent: input.agent ?? this.#agent, task: message });
+  }
+  async #runChat(input, message) {
+    if (this.#conversation === void 0) {
+      return Result.fail(ErrorCodes.BrainProviderUnavailable);
+    }
+    const result = await this.#conversation.chat(chatInput(input, message), {
+      approved: input.approved,
+      interface: input.interface ?? "cli",
+      requestedBy: "agent.chat"
+    });
+    if (result.isErr()) {
+      return Result.fail(result.unwrapError());
+    }
+    const conversation = result.unwrap();
+    input.onEvent?.({ reply: conversation.reply, type: "final" });
+    return Result.ok({
+      conversation,
+      mode: "chat",
+      reply: conversation.reply,
+      steps: []
+    });
+  }
+};
 
 // src/app/mcp/mcp_result_mapper.ts
 function inputSchemaWithAgentControl(tool) {
@@ -8396,6 +8674,11 @@ var agentTaskTool = {
   annotations: { openWorldHint: true },
   _meta: { "agent-devkit/kind": "agent-delegation" }
 };
+var baseInstructions = "Agent DevKit exposes local capabilities as MCP tools, plus an `agent.task` delegation tool. Prefer `agent.task` for bounded, multi-step or routine local tasks to offload orchestration and reduce token usage; use the individual capability tools directly when you need step-by-step control or precise intermediate results. Risky tools require explicit approval through _agent.approved. For agent.task, approval must be scoped with approvedTools.";
+var surfaceResourceInstructions = " Per-module guidance (purpose, when to use, guardrails) is available as MCP resources under agent-devkit://surface/<moduleId>; read them to route between agent.task and direct capability tools.";
+function surfaceResourceUri(moduleId) {
+  return `agent-devkit://surface/${moduleId}`;
+}
 function mcpToolFromRuntimeTool(tool) {
   const mcpTool = {
     name: tool.id,
@@ -8418,21 +8701,37 @@ function mcpToolFromRuntimeTool(tool) {
   }
   return mcpTool;
 }
+async function currentAgentPersona(personalization) {
+  const profile = await personalization.loadProfile();
+  if (profile.isErr()) {
+    return void 0;
+  }
+  const character = profile.unwrap().currentCharacter;
+  return {
+    behavior: character.profile.behavior,
+    characterId: character.id,
+    detailLevel: character.profile.detailLevel,
+    name: character.name ?? character.id,
+    tone: character.profile.tone,
+    traits: character.profile.traits
+  };
+}
 function createAgentMcpServer(options) {
+  const knowledge = options.knowledge;
+  const personalization = new PersonalizationRepository();
   const server = new Server(
     {
       name: options.packageName,
       version: options.version
     },
     {
-      capabilities: {
-        tools: {}
-      },
-      instructions: "Agent DevKit exposes local capabilities as MCP tools, plus an `agent.task` delegation tool. Prefer `agent.task` for bounded, multi-step or routine local tasks to offload orchestration and reduce token usage; use the individual capability tools directly when you need step-by-step control or precise intermediate results. Risky tools require explicit approval through _agent.approved. For agent.task, approval must be scoped with approvedTools."
+      capabilities: knowledge === void 0 ? { tools: {} } : { resources: {}, tools: {} },
+      instructions: knowledge === void 0 ? baseInstructions : `${baseInstructions}${surfaceResourceInstructions}`
     }
   );
   const agent = new AgentRuntime({
     brainProvider: createBrainDockProvider({ stateDirectory: join16(homedir13(), ".agent-devkit") }),
+    knowledge,
     toolRuntime: options.runtime
   });
   server.setRequestHandler(ListToolsRequestSchema, async () => ({
@@ -8446,7 +8745,13 @@ function createAgentMcpServer(options) {
       if (task.length === 0) {
         return { content: [{ type: "text", text: "Missing 'task'." }], isError: true };
       }
-      const run = await agent.run({ approvedTools, task });
+      const run = await agent.run({
+        agent: await currentAgentPersona(personalization),
+        approvedTools,
+        interface: "mcp",
+        mode: "task",
+        task
+      });
       if (run.isErr()) {
         return {
           content: [{ type: "text", text: `Agent run failed: ${run.unwrapError()}` }],
@@ -8480,6 +8785,37 @@ ${stepsText}` : payload.reply
     const tool = options.runtime.getTool(request.params.name);
     return runtimeResultToMcpContent(result, tool.isOk() && hasObjectOutputSchema(tool.unwrap()));
   });
+  if (knowledge !== void 0) {
+    server.setRequestHandler(ListResourcesRequestSchema, async () => {
+      const modules = await knowledge.all();
+      return {
+        resources: modules.map((module) => ({
+          description: module.summary,
+          mimeType: "application/json",
+          name: `${module.moduleId} surface`,
+          uri: surfaceResourceUri(module.moduleId)
+        }))
+      };
+    });
+    server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+      const modules = await knowledge.all();
+      const module = modules.find(
+        (entry) => surfaceResourceUri(entry.moduleId) === request.params.uri
+      );
+      if (module === void 0) {
+        throw new Error(`Unknown resource: ${request.params.uri}`);
+      }
+      return {
+        contents: [
+          {
+            mimeType: "application/json",
+            text: JSON.stringify(module, null, 2),
+            uri: request.params.uri
+          }
+        ]
+      };
+    });
+  }
   return server;
 }
 
@@ -8577,6 +8913,7 @@ function runtime2(options) {
 }
 async function runStdio(options) {
   await startMcpStdioServer({
+    knowledge: createModuleSurfaceKnowledge(),
     packageName: options.packageName,
     runtime: runtime2(options),
     version: options.currentVersion
@@ -8631,6 +8968,7 @@ function registerMcpCommand(program2, options) {
         const server = await startMcpHttpServer({
           allowedOrigins: commandOptions.origin,
           host: commandOptions.host,
+          knowledge: createModuleSurfaceKnowledge(),
           packageName: options.packageName,
           port: parsePositiveInteger(commandOptions.port),
           runtime: runtime2(options),
@@ -9710,6 +10048,16 @@ function registerSecretsCommand(program2, options) {
 }
 
 // src/app/cli/commands/sessionsCommand.ts
+function stringOption(options, ...names) {
+  const nested = typeof options.opts === "function" ? options.opts() : {};
+  for (const name of names) {
+    const value = options[name] ?? nested[name];
+    if (typeof value === "string" && value.length > 0) {
+      return value;
+    }
+  }
+  return void 0;
+}
 function parseTags2(value) {
   const tags = value?.split(",").map((tag) => tag.trim()).filter((tag) => tag.length > 0);
   return tags === void 0 || tags.length === 0 ? void 0 : tags;
@@ -9742,14 +10090,14 @@ function registerSessionsCommand(program2, options) {
         await printSessionsResult(commandOptions, {
           action: "list",
           limit: parseNonNegativeInteger(commandOptions.limit),
-          projectId: commandOptions.project,
+          projectId: stringOption(commandOptions, "project", "projectId"),
           query: commandOptions.query,
           status: commandOptions.status
         });
       }
     )
   );
-  const createCommand = sessionsCommand.command("create").description("create a context session").option("--json", "print session result as JSON").option("--origin <origin>", "cli, tui, mcp or agent", "cli").option("--project <projectId>", "project id").option("--tags <tags>", "comma-separated tags").option("--title <title>", "session title");
+  const createCommand = sessionsCommand.command("create").description("create a context session").option("--json", "print session result as JSON").option("--origin <origin>", "cli, tui, mcp or agent", "cli").option("--tags <tags>", "comma-separated tags").option("--title <title>", "session title");
   createCommand.action(
     options.usageLogging.track(
       { area: "user", command: "sessions.create", options: () => createCommand.opts() },
@@ -9757,7 +10105,7 @@ function registerSessionsCommand(program2, options) {
         await printSessionsResult(commandOptions, {
           action: "create",
           origin: commandOptions.origin ?? "cli",
-          projectId: commandOptions.project,
+          projectId: stringOption(commandOptions, "project", "projectId") ?? stringOption(sessionsCommand.opts(), "project", "projectId"),
           tags: parseTags2(commandOptions.tags),
           title: commandOptions.title
         });
@@ -9793,7 +10141,7 @@ function registerSessionsCommand(program2, options) {
       }
     )
   );
-  const searchCommand = sessionsCommand.command("search").argument("<query>", "query").description("search context sessions").option("--json", "print session result as JSON").option("--limit <limit>", "maximum number of results").option("--project <projectId>", "project id");
+  const searchCommand = sessionsCommand.command("search").argument("<query>", "query").description("search context sessions").option("--json", "print session result as JSON").option("--limit <limit>", "maximum number of results");
   searchCommand.action(
     options.usageLogging.track(
       { area: "user", command: "sessions.search", options: () => searchCommand.opts() },
@@ -9801,7 +10149,7 @@ function registerSessionsCommand(program2, options) {
         await printSessionsResult(commandOptions, {
           action: "search",
           limit: parseNonNegativeInteger(commandOptions.limit),
-          projectId: commandOptions.project,
+          projectId: stringOption(commandOptions, "project", "projectId") ?? stringOption(sessionsCommand.opts(), "project", "projectId"),
           query
         });
       }
@@ -10073,10 +10421,7 @@ import { homedir as homedir22 } from "os";
 
 // src/modules/conversation/capabilities/chat/chat.viewmodel.ts
 function formatConversationChatText(result) {
-  const agentName = result.prompt.agent.name.trim();
   const reply2 = result.reply.trim();
-  const speakerPrefix = `${agentName}:`;
-  const normalizedReply = reply2.toLowerCase().startsWith(speakerPrefix.toLowerCase()) ? reply2 : `${speakerPrefix} ${reply2}`;
   const metadata = [`Session: ${result.sessionId}`];
   if (result.projectId !== void 0) {
     metadata.push(`Project: ${result.projectId}`);
@@ -10096,20 +10441,28 @@ function formatConversationChatText(result) {
       metadata.push(`Tokens: ${tokens.join(", ")}`);
     }
   }
-  return [normalizedReply, "", ...metadata].join("\n");
+  return [reply2, "", ...metadata].join("\n");
 }
 
 // src/app/cli/rootConversation.ts
-var cliConversationStatePath = {
-  namespace: "conversation",
-  segments: ["cli-state.json"]
-};
+function sanitizeCliScope(scope) {
+  return scope.replaceAll(/[^a-zA-Z0-9_-]+/g, "-").replaceAll(/^-+|-+$/g, "") || "default";
+}
+function currentCliSessionScope() {
+  return process.env.AGENT_DEVKIT_CLI_SESSION_SCOPE ?? String(process.ppid);
+}
+function cliConversationStatePathForScope(scope) {
+  return {
+    namespace: "conversation",
+    segments: [`cli-state-${sanitizeCliScope(scope)}.json`]
+  };
+}
 function isCliConversationState(value) {
   const record = value;
   return typeof value === "object" && value !== null && "activeSessionId" in value && "schema" in value && typeof record.activeSessionId === "string" && record.activeSessionId.length > 0 && record.schema === "agent-devkit.cli-conversation-state/v1";
 }
-async function loadActiveCliSessionId(dataStore, sessions) {
-  const state = await dataStore.readJson(cliConversationStatePath);
+async function loadActiveCliSessionId(dataStore, sessions, statePath) {
+  const state = await dataStore.readJson(statePath);
   if (state.isErr()) {
     return void 0;
   }
@@ -10131,9 +10484,9 @@ async function loadActiveCliSessionId(dataStore, sessions) {
   }
   return result.session.id;
 }
-async function saveActiveCliSessionId(dataStore, sessionId) {
+async function saveActiveCliSessionId(dataStore, sessionId, statePath) {
   await dataStore.writeJson(
-    cliConversationStatePath,
+    statePath,
     {
       activeSessionId: sessionId,
       schema: "agent-devkit.cli-conversation-state/v1",
@@ -10142,7 +10495,31 @@ async function saveActiveCliSessionId(dataStore, sessionId) {
     { atomic: true }
   );
 }
-async function runRootConversation(message) {
+function createConversationPort(chat) {
+  return {
+    chat: async (input, context) => {
+      const result = await chat.invoke(
+        {
+          action: "send",
+          characterId: input.characterId,
+          includeHistory: input.includeHistory,
+          message: input.message,
+          projectId: input.projectId,
+          sessionId: input.sessionId
+        },
+        context
+      );
+      return result.map((payload) => ({
+        brain: payload.brain,
+        projectId: payload.projectId,
+        raw: payload,
+        reply: payload.reply,
+        sessionId: payload.sessionId
+      }));
+    }
+  };
+}
+async function runRootConversation(message, options) {
   const homeDirectory = homedir22();
   const dataStore = new LocalAgentDataStore({
     rootDirectory: `${homeDirectory}/.agent-devkit/data`
@@ -10159,21 +10536,40 @@ async function runRootConversation(message) {
   if (contextBindings.isErr()) {
     throw new Error(contextBindings.unwrapError());
   }
+  const cliStatePath = cliConversationStatePathForScope(currentCliSessionScope());
   const activeSessionId = await loadActiveCliSessionId(
     dataStore,
-    contextBindings.unwrap().capabilities.sessions
+    contextBindings.unwrap().capabilities.sessions,
+    cliStatePath
   );
-  const result = await bindings.unwrap().capabilities.chat.execute({
-    action: "send",
+  const agent = new AgentRuntime({
+    brainProvider: createBrainDockProvider({ stateDirectory: `${homeDirectory}/.agent-devkit` }),
+    conversation: createConversationPort(bindings.unwrap().capabilities.chat),
+    toolRuntime: createCliToolRuntime({
+      currentVersion: options.currentVersion,
+      packageName: options.packageName
+    })
+  });
+  const result = await agent.run({
+    interface: "cli",
     message,
+    mode: "chat",
     sessionId: activeSessionId
   });
   if (result.isErr()) {
     throw new Error(result.unwrapError());
   }
   const payload = result.unwrap();
-  await saveActiveCliSessionId(dataStore, payload.sessionId);
-  console.log(formatConversationChatText(payload));
+  const rawConversation = payload.conversation?.raw;
+  if (payload.conversation === void 0 || !isConversationChatResult(rawConversation)) {
+    throw new Error("Agent did not return a conversation result.");
+  }
+  await saveActiveCliSessionId(dataStore, payload.conversation.sessionId, cliStatePath);
+  console.log(formatConversationChatText(rawConversation));
+}
+function isConversationChatResult(value) {
+  const candidate = value;
+  return typeof value === "object" && value !== null && candidate.action === "send" && typeof candidate.reply === "string" && typeof candidate.sessionId === "string";
 }
 
 // src/infra/helpers/redaction.ts
@@ -10514,7 +10910,10 @@ program.name("agent").description(translator.t("cli.root.description")).version(
       program.error(translator.t("cli.root.removedChatCommand"));
     }
     if (initialPrompt.length > 0) {
-      await runRootConversation(initialPrompt);
+      await runRootConversation(initialPrompt, {
+        currentVersion: package_default.version,
+        packageName: package_default.name
+      });
       return;
     }
     await ensureFirstRunModel(translator);