palmier 0.6.7 → 0.6.8

package/src/agents/kimi.ts

@@ -15,7 +15,7 @@ export class KimiAgent implements AgentTool {
 
   getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
     const yolo = extraPermissions === "yolo";
-    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const prompt = followupPrompt ?? getAgentInstructions(task, yolo || !this.supportsPermissions);
     const args = [];
 
     if (yolo) {

package/src/agents/kiro.ts

@@ -15,7 +15,7 @@ export class Kiro implements AgentTool {
 
   getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
     const yolo = extraPermissions === "yolo";
-    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const prompt = followupPrompt ?? getAgentInstructions(task, yolo || !this.supportsPermissions);
     const args = [];
 
     if (yolo) {

package/src/agents/openclaw.ts

@@ -14,7 +14,7 @@ export class OpenClawAgent implements AgentTool {
 
   getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
     const yolo = extraPermissions === "yolo";
-    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const prompt = followupPrompt ?? getAgentInstructions(task, yolo || !this.supportsPermissions);
     // OpenClaw does not support stdin as prompt.
     const args = ["agent", "--local", "--session-id", task.frontmatter.id, "--message", prompt];
 

package/src/agents/opencode.ts

@@ -15,7 +15,7 @@ export class OpenCodeAgent implements AgentTool {
 
   getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
     const yolo = extraPermissions === "yolo";
-    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const prompt = followupPrompt ?? getAgentInstructions(task, yolo || !this.supportsPermissions);
     const args = ["run"];
 
     if (yolo) {

package/src/agents/qoder.ts

@@ -15,7 +15,7 @@ export class Qoder implements AgentTool {
 
   getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
     const yolo = extraPermissions === "yolo";
-    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const prompt = followupPrompt ?? getAgentInstructions(task, yolo || !this.supportsPermissions);
     const args = [];
 
     if (yolo) {

package/src/agents/qwen.ts

@@ -15,7 +15,7 @@ export class QwenAgent implements AgentTool {
 
   getTaskRunCommandLine(task: ParsedTask, followupPrompt?: string, extraPermissions?: RequiredPermission[] | "yolo"): CommandLine {
     const yolo = extraPermissions === "yolo";
-    const prompt = followupPrompt ?? (getAgentInstructions(task.frontmatter.id, yolo || !this.supportsPermissions) + "\n\n" + (task.body || task.frontmatter.user_prompt));
+    const prompt = followupPrompt ?? getAgentInstructions(task, yolo || !this.supportsPermissions);
     const args = ["--approval-mode", yolo ? "yolo" : "auto-edit"];
 
     if (followupPrompt) { args.push("-c"); }

package/src/agents/shared-prompt.ts

@@ -2,6 +2,8 @@ import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
 import { loadConfig } from "../config.js";
+import { generateEndpointDocs } from "../mcp-tools.js";
+import type { ParsedTask } from "../types.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
@@ -11,13 +13,14 @@ const AGENT_INSTRUCTIONS_TEMPLATE = fs.readFileSync(
 );
 
 /**
- * Agent instructions with the serve daemon's HTTP port and task ID baked in.
+ * Build the full agent prompt: instructions + endpoint docs + task description.
  */
-export function getAgentInstructions(taskId: string, skipPermissions?: boolean): string {
+export function getAgentInstructions(task: ParsedTask, skipPermissions?: boolean): string {
   const port = loadConfig().httpPort ?? 9966;
+  const taskDescription = task.body || task.frontmatter.user_prompt;
   let instructions = AGENT_INSTRUCTIONS_TEMPLATE
-    .replace(/\{\{PORT\}\}/g, String(port))
-    .replace(/\{\{TASK_ID\}\}/g, taskId);
+    .replace(/\{\{ENDPOINT_DOCS\}\}/g, generateEndpointDocs(port, task.frontmatter.id))
+    .replace(/\{\{TASK_DESCRIPTION\}\}/g, taskDescription);
   if (skipPermissions) {
     instructions = instructions.replace(/## Permissions\r?\n[\s\S]*?(?=## |\r?\n---)/m, "");
   }

package/src/commands/run.ts

@@ -65,9 +65,6 @@ async function invokeAgentWithRetries(
     const { command, args, stdin, env: agentEnv } = ctx.agent.getTaskRunCommandLine(
       invokeTask, undefined, ctx.task.frontmatter.yolo_mode ? "yolo" : ctx.transientPermissions,
     );
-    const truncate = (s: string, max = 100) => s.length > max ? s.slice(0, max) + "…" : s;
-    const displayArgs = args.map((a) => truncate(a));
-    console.log(`[invoke] ${command} ${displayArgs.join(" ")}${stdin ? ` (stdin: ${truncate(stdin, 100)})` : ""}`);
     const result = await spawnCommand(command, args, {
       cwd: getRunDir(ctx.taskDir, ctx.runId),
       env: { ...ctx.guiEnv, ...agentEnv, PALMIER_RUN_DIR: getRunDir(ctx.taskDir, ctx.runId), PALMIER_HTTP_PORT: String(ctx.config.httpPort ?? 9966) },
@@ -516,10 +513,10 @@ async function requestConfirmation(
   taskDir: string,
 ): Promise<boolean> {
   const port = config.httpPort ?? 9966;
-  const res = await fetch(`http://localhost:${port}/request-confirmation`, {
+  const res = await fetch(`http://localhost:${port}/request-confirmation?taskId=${encodeURIComponent(task.frontmatter.id)}`, {
     method: "POST",
     headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({ taskId: task.frontmatter.id, description: `Run task "${task.frontmatter.name || task.frontmatter.id}"?` }),
+    body: JSON.stringify({ description: `Run task "${task.frontmatter.name || task.frontmatter.id}"?` }),
   });
   const body = await res.json() as { confirmed?: boolean; error?: string };
   if (typeof body.confirmed !== "boolean") {

package/src/mcp-handler.ts

@@ -90,7 +90,7 @@ export async function handleMcpRequest(body: string, sessionId: string | undefin
         body: rpcResult(id, {
           tools: agentTools.map((t) => ({
             name: t.name,
-            description: t.description,
+            description: t.description.join(" "),
             inputSchema: t.inputSchema,
           })),
         }),

package/src/mcp-tools.ts

@@ -19,14 +19,18 @@ export interface ToolContext {
 
 export interface ToolDefinition {
   name: string;
-  description: string;
+  /** First line is the summary (used as endpoint header). Remaining lines become bullet points in docs. */
+  description: string[];
   inputSchema: object;
   handler: (args: Record<string, unknown>, ctx: ToolContext) => Promise<unknown>;
 }
 
 const notifyTool: ToolDefinition = {
   name: "notify",
-  description: "Send a push notification to the user's device.",
+  description: [
+    "Send a push notification to the user's device.",
+    'Response: `{"ok": true}` on success.',
+  ],
   inputSchema: {
     type: "object",
     properties: {
@@ -55,7 +59,12 @@ const notifyTool: ToolDefinition = {
 
 const requestInputTool: ToolDefinition = {
   name: "request-input",
-  description: "Request input from the user. The request blocks until the user responds.",
+  description: [
+    "Request input from the user.",
+    "The request blocks until the user responds.",
+    'Response: `{"values": ["answer1", "answer2"]}` on success, or `{"aborted": true}` if the user declines.',
+    "When you need information from the user (credentials, answers to questions, preferences, clarifications, etc.), do not guess, fail, or prompt via stdout, even in a non-interactive environment — use this endpoint instead.",
+  ],
   inputSchema: {
     type: "object",
     properties: {
@@ -87,18 +96,28 @@ const requestInputTool: ToolDefinition = {
     const response = await pendingPromise;
 
     if (response.length === 1 && response[0] === "aborted") {
-      await ctx.publishEvent("_input", { event_type: "input-resolved", host_id: ctx.config.hostId, session_id: ctx.sessionId, status: "aborted" });
+      await ctx.publishEvent("_input", {
+        event_type: "input-resolved", host_id: ctx.config.hostId,
+        session_id: ctx.sessionId, status: "aborted",
+      });
       return { aborted: true };
     }
 
-    await ctx.publishEvent("_input", { event_type: "input-resolved", host_id: ctx.config.hostId, session_id: ctx.sessionId, status: "provided" });
+    await ctx.publishEvent("_input", {
+      event_type: "input-resolved", host_id: ctx.config.hostId,
+      session_id: ctx.sessionId, status: "provided",
+    });
     return { values: response };
   },
 };
 
 const requestConfirmationTool: ToolDefinition = {
   name: "request-confirmation",
-  description: "Request confirmation from the user. The request blocks until the user confirms or aborts.",
+  description: [
+    "Request confirmation from the user.",
+    "The request blocks until the user confirms or aborts.",
+    'Response: `{"confirmed": true}` or `{"confirmed": false}`.',
+  ],
   inputSchema: {
     type: "object",
     properties: {
@@ -136,7 +155,12 @@ const requestConfirmationTool: ToolDefinition = {
 
 const deviceGeolocationTool: ToolDefinition = {
   name: "device-geolocation",
-  description: "Get the GPS location of the user's mobile device. Blocks until the device responds (up to 30 seconds).",
+  description: [
+    "Get the GPS location of the user's mobile device.",
+    "When you need the user's real-time location, use this endpoint.",
+    "Blocks until the device responds (up to 30 seconds).",
+    'Response: `{"latitude": ..., "longitude": ..., "accuracy": ..., "timestamp": ...}` on success, or `{"error": "..."}` on failure.',
+  ],
   inputSchema: {
     type: "object",
     properties: {},
@@ -180,3 +204,50 @@ const deviceGeolocationTool: ToolDefinition = {
 
 export const agentTools: ToolDefinition[] = [notifyTool, requestInputTool, requestConfirmationTool, deviceGeolocationTool];
 export const agentToolMap = new Map<string, ToolDefinition>(agentTools.map((t) => [t.name, t]));
+
+/**
+ * Generate the HTTP Endpoints markdown section for agent-instructions.md from the tool registry.
+ */
+export function generateEndpointDocs(port: number, taskId: string): string {
+  const baseUrl = `http://localhost:${port}`;
+  const lines: string[] = [
+    `The following HTTP endpoints are available during task execution. Use curl to call them.`,
+    "",
+  ];
+
+  for (const tool of agentTools) {
+    const schema = tool.inputSchema as { properties?: Record<string, { type?: string; description?: string; items?: { type?: string } }>; required?: string[] };
+    const props = schema.properties ?? {};
+    const required = new Set(schema.required ?? []);
+
+    // Build example JSON (body only, no taskId)
+    const example: Record<string, unknown> = {};
+    for (const [key, prop] of Object.entries(props)) {
+      if (prop.type === "array") example[key] = ["..."];
+      else example[key] = "...";
+    }
+
+    const queryUrl = `${baseUrl}/${tool.name}?taskId=${taskId}`;
+    const [header, ...details] = tool.description;
+
+    lines.push(`**\`POST ${queryUrl}\`** — ${header}`);
+    if (Object.keys(example).length > 0) {
+      lines.push("```json");
+      lines.push(JSON.stringify(example));
+      lines.push("```");
+    }
+    for (const [key, prop] of Object.entries(props)) {
+      const req = required.has(key) ? "required" : "optional";
+      let typeStr = prop.type ?? "unknown";
+      if (prop.type === "array" && prop.items?.type) typeStr = `${prop.items.type} array`;
+      lines.push(`- \`${key}\` (${req}, ${typeStr}): ${prop.description ?? ""}`);
+    }
+    for (const detail of details) {
+      lines.push(`- ${detail}`);
+    }
+
+    lines.push("");
+  }
+
+  return lines.join("\n").trimEnd();
+}

package/src/rpc-handler.ts

@@ -126,7 +126,6 @@ async function generatePlan(
   const fullPrompt = PLAN_GENERATION_PROMPT + userPrompt;
   const planAgent = getAgent(agentName);
   const { command, args, stdin, env: agentEnv } = planAgent.getPlanGenerationCommandLine(fullPrompt);
-  console.log(`[generatePlan] Running: ${command} ${args.join(" ")}`);
 
   const { output } = await spawnCommand(command, args, {
     cwd: projectRoot,

package/src/spawn-command.ts

@@ -89,8 +89,10 @@ export function spawnCommand(
     const finalArgs = process.platform === "win32"
       ? args.map((a) => a.replace(/[\r\n]+/g, " "))
       : args;
+    const truncate = (s: string, max = 100) => s.length > max ? s.slice(0, max) + "..." : s;
+    const displayArgs = finalArgs.map((arg) => truncate(arg));
 
-    // console.log(`[spawn] ${command} ${finalArgs.join(" ")}`);
+    console.log(`[spawn] ${command} ${displayArgs.join(" ")}`);
 
     const child = crossSpawn(command, finalArgs, {
       cwd: opts.cwd,

package/src/transports/http-transport.ts

@@ -195,11 +195,9 @@ export async function startHttpTransport(
       if (!isLocalhost(req)) { sendJson(res, 403, { error: "localhost only" }); return; }
       const tool = agentToolMap.get(pathname.slice(1))!;
       try {
-        const body = await readBody(req);
-        const args = body.trim() ? JSON.parse(body) : {};
-        const { taskId } = args as { taskId?: string };
+        const taskId = url.searchParams.get("taskId");
         if (!taskId) {
-          sendJson(res, 400, { error: "taskId is required" });
+          sendJson(res, 400, { error: "taskId query parameter is required" });
           return;
         }
         const taskDir = getTaskDir(config.projectRoot, taskId);
@@ -207,7 +205,8 @@ export async function startHttpTransport(
           sendJson(res, 404, { error: `Task not found: ${taskId}` });
           return;
         }
-        delete args.taskId;
+        const body = await readBody(req);
+        const args = body.trim() ? JSON.parse(body) : {};
         const ctx = makeToolContext(taskId);
         console.log(`[mcp] REST [${taskId.slice(0, 8)}] ${tool.name}`);
         const result = await tool.handler(args, ctx);

package/test/agent-instructions.test.ts

@@ -3,6 +3,7 @@ import assert from "node:assert/strict";
 import * as fs from "fs";
 import * as path from "path";
 import { fileURLToPath } from "url";
+import { generateEndpointDocs, agentTools } from "../src/mcp-tools.js";
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const templatePath = path.join(__dirname, "..", "src", "agents", "agent-instructions.md");
@@ -11,8 +12,8 @@ const template = fs.readFileSync(templatePath, "utf-8");
 /** Minimal replica of getAgentInstructions that doesn't need host.json */
 function buildInstructions(taskId: string, skipPermissions?: boolean): string {
   let instructions = template
-    .replace(/\{\{PORT\}\}/g, "9966")
-    .replace(/\{\{TASK_ID\}\}/g, taskId);
+    .replace(/\{\{ENDPOINT_DOCS\}\}/g, generateEndpointDocs(9966, taskId))
+    .replace(/\{\{TASK_DESCRIPTION\}\}/g, "Test task prompt");
   if (skipPermissions) {
     instructions = instructions.replace(/## Permissions\r?\n[\s\S]*?(?=## |\r?\n---)/m, "");
   }
@@ -39,10 +40,72 @@ describe("getAgentInstructions", () => {
     assert.match(result, /## HTTP Endpoints/);
   });
 
-  it("replaces template variables", () => {
+  it("replaces all template variables", () => {
+    const result = buildInstructions("my-task-123");
+    assert.doesNotMatch(result, /\{\{ENDPOINT_DOCS\}\}/);
+    assert.doesNotMatch(result, /\{\{TASK_DESCRIPTION\}\}/);
+  });
+
+  it("includes task ID in endpoint examples", () => {
     const result = buildInstructions("my-task-123");
     assert.match(result, /my-task-123/);
-    assert.doesNotMatch(result, /\{\{TASK_ID\}\}/);
-    assert.doesNotMatch(result, /\{\{PORT\}\}/);
+  });
+
+  it("includes port in endpoint URL", () => {
+    const result = buildInstructions("test");
+    assert.match(result, /localhost:9966/);
+  });
+
+  it("includes task description", () => {
+    const result = buildInstructions("test");
+    assert.match(result, /Test task prompt/);
+  });
+});
+
+describe("full agent instruction snapshot", () => {
+  it("matches the expected full text exactly", () => {
+    const result = buildInstructions("test-task-id").replace(/\r\n/g, "\n").trimEnd();
+    const snapshotPath = path.join(__dirname, "fixtures", "agent-instructions-snapshot.md");
+    const expected = fs.readFileSync(snapshotPath, "utf-8").replace(/\r\n/g, "\n").trimEnd();
+    assert.equal(result, expected);
+  });
+});
+
+describe("generateEndpointDocs", () => {
+  const docs = generateEndpointDocs(9966, "test-id");
+
+  it("generates docs for all MCP tools", () => {
+    for (const tool of agentTools) {
+      assert.match(docs, new RegExp(`POST http://localhost:9966/${tool.name}\\?taskId=`), `Missing endpoint for ${tool.name}`);
+    }
+  });
+
+  it("includes taskId parameter for every endpoint", () => {
+    const endpointBlocks = docs.split("**`POST");
+    // First element is the header, skip it
+    for (let i = 1; i < endpointBlocks.length; i++) {
+      assert.match(endpointBlocks[i], /taskId/, `Missing taskId in endpoint block ${i}`);
+    }
+  });
+
+  it("includes port in the header", () => {
+    assert.match(docs, /localhost:9966/);
+  });
+
+  it("includes task ID in query parameters", () => {
+    assert.match(docs, /taskId=test-id/);
+  });
+
+  it("includes response descriptions", () => {
+    for (const tool of agentTools) {
+      if (tool.responseDescription) {
+        assert.match(docs, /Response:/, `Missing response description for ${tool.name}`);
+      }
+    }
+  });
+
+  it("marks required and optional parameters correctly", () => {
+    assert.match(docs, /\(required, string\)/);
+    assert.match(docs, /\(optional, string\)/);
   });
 });

package/test/fixtures/agent-instructions-snapshot.md

@@ -0,0 +1,58 @@
+You are an AI agent executing a task on behalf of the user. Follow these instructions carefully.
+
+## Reporting Output
+
+If you generate report or output files, print each file path on its own line using this exact format:
+[PALMIER_REPORT] <filename>
+
+## Completion
+
+When you are done, output exactly one of these markers as the very last line (no other text on the same line):
+[PALMIER_TASK_SUCCESS]
+[PALMIER_TASK_FAILURE]
+
+## Permissions
+
+Whenever a tool you are trying to use is denied or you lack the required permissions, print each required permission on its own line using this exact format:
+[PALMIER_PERMISSION] <tool_name> | <description>
+
+## HTTP Endpoints
+
+The following HTTP endpoints are available during task execution. Use curl to call them.
+
+**`POST http://localhost:9966/notify?taskId=test-task-id`** — Send a push notification to the user's device.
+```json
+{"title":"...","body":"..."}
+```
+- `title` (required, string): Notification title
+- `body` (required, string): Notification body
+- Response: `{"ok": true}` on success.
+
+**`POST http://localhost:9966/request-input?taskId=test-task-id`** — Request input from the user.
+```json
+{"description":"...","questions":["..."]}
+```
+- `description` (optional, string): Context or heading for the input request
+- `questions` (required, string array): Questions to present to the user
+- The request blocks until the user responds.
+- Response: `{"values": ["answer1", "answer2"]}` on success, or `{"aborted": true}` if the user declines.
+- When you need information from the user (credentials, answers to questions, preferences, clarifications, etc.), do not guess, fail, or prompt via stdout, even in a non-interactive environment — use this endpoint instead.
+
+**`POST http://localhost:9966/request-confirmation?taskId=test-task-id`** — Request confirmation from the user.
+```json
+{"description":"..."}
+```
+- `description` (required, string): What the user is confirming
+- The request blocks until the user confirms or aborts.
+- Response: `{"confirmed": true}` or `{"confirmed": false}`.
+
+**`POST http://localhost:9966/device-geolocation?taskId=test-task-id`** — Get the GPS location of the user's mobile device.
+- When you need the user's real-time location, use this endpoint.
+- Blocks until the device responds (up to 30 seconds).
+- Response: `{"latitude": ..., "longitude": ..., "accuracy": ..., "timestamp": ...}` on success, or `{"error": "..."}` on failure.
+
+The task to execute follows below:
+
+---
+
+Test task prompt