@flue/client 0.0.16 → 0.0.18

package/dist/index.d.mts

@@ -100,8 +100,6 @@ interface SkillOptions<S extends v.GenericSchema | undefined = undefined> {
     providerID: string;
     modelID: string;
   };
-  /** Advanced: override the entire prompt. */
-  prompt?: string;
 }
 interface PromptOptions<S extends v.GenericSchema | undefined = undefined> {
   /** Valibot schema for structured result extraction. */

package/dist/index.mjs

@@ -1,6 +1,6 @@
 import { createOpencodeClient } from "@opencode-ai/sdk";
-import { exec } from "node:child_process";
 import { toJsonSchema } from "@valibot/to-json-schema";
+import { exec } from "node:child_process";
 import * as v from "valibot";
 
 //#region src/errors.ts
@@ -162,6 +162,66 @@ function transformEvent(raw) {
 	return null;
 }
 
+//#endregion
+//#region src/prompt.ts
+/**
+* Preamble instructing the LLM to operate autonomously without user interaction.
+*/
+const HEADLESS_PREAMBLE = "You are running in headless mode with no human operator. Work autonomously — never ask questions, never wait for user input, never use the question tool. Make your best judgment and proceed independently.";
+/**
+* Checks if a skill name is a file path (contains '/' or ends with '.md').
+*/
+function isFilePath(name) {
+	return name.includes("/") || name.endsWith(".md");
+}
+/**
+* Build the ---RESULT_START--- / ---RESULT_END--- extraction instructions
+* for a given Valibot schema.
+*/
+function buildResultInstructions(schema) {
+	const { $schema: _, ...schemaWithoutMeta } = toJsonSchema(schema, { errorMode: "ignore" });
+	return [
+		"",
+		"When complete, you MUST output your result between these exact delimiters conforming to this schema:",
+		"```json",
+		JSON.stringify(schemaWithoutMeta, null, 2),
+		"```",
+		"",
+		"Example: (Object)",
+		"---RESULT_START---",
+		"{\"key\": \"value\"}",
+		"---RESULT_END---",
+		"",
+		"Example: (String)",
+		"---RESULT_START---",
+		"Hello, world!",
+		"---RESULT_END---"
+	].join("\n");
+}
+/**
+* Build the prompt text for a skill invocation.
+*
+* If `name` looks like a file path (contains '/' or ends with '.md'), the
+* prompt instructs the agent to read and follow that file under
+* `.agents/skills/`. Otherwise, it instructs the agent to use the named
+* skill.
+*
+* @param name - A skill name or a file path relative to .agents/skills/.
+* @param args - Key-value arguments to include in the prompt.
+* @param schema - Optional Valibot schema for result extraction.
+* @returns The complete prompt string.
+*/
+function buildSkillPrompt(name, args, schema) {
+	const parts = [
+		HEADLESS_PREAMBLE,
+		"",
+		isFilePath(name) ? `Read the file .agents/skills/${name} directly from disk (do not use the skill tool) and follow it as your skill instructions.` : `Use the ${name} skill.`
+	];
+	if (args && Object.keys(args).length > 0) parts.push(`\nArguments:\n${JSON.stringify(args, null, 2)}`);
+	if (schema) parts.push(buildResultInstructions(schema));
+	return parts.join("\n");
+}
+
 //#endregion
 //#region src/shell.ts
 async function runShell(command, options) {
@@ -202,41 +262,6 @@ async function runShell(command, options) {
 	});
 }
 
-//#endregion
-//#region src/prompt.ts
-/**
-* Checks if a skill name is a file path (contains '/' or ends with '.md').
-*/
-function isFilePath(name) {
-	return name.includes("/") || name.endsWith(".md");
-}
-/**
-* Build the prompt text for a skill invocation.
-*
-* If `name` looks like a file path (contains '/' or ends with '.md'), the
-* prompt instructs the agent to read and follow that file under
-* `.agents/skills/`. Otherwise, it instructs the agent to use the named
-* skill.
-*
-* @param name - A skill name or a file path relative to .agents/skills/.
-* @param args - Key-value arguments to include in the prompt.
-* @param schema - Optional Valibot schema for result extraction.
-* @returns The complete prompt string.
-*/
-function buildSkillPrompt(name, args, schema) {
-	const parts = [
-		"You are running in headless mode with no human operator. Work autonomously — never ask questions, never wait for user input, never use the question tool. Make your best judgment and proceed independently.",
-		"",
-		isFilePath(name) ? `Read and use the .agents/skills/${name} skill.` : `Use the ${name} skill.`
-	];
-	if (args && Object.keys(args).length > 0) parts.push(`\nArguments:\n${JSON.stringify(args, null, 2)}`);
-	if (schema) {
-		const { $schema: _, ...schemaWithoutMeta } = toJsonSchema(schema, { errorMode: "ignore" });
-		parts.push("\nWhen complete, you MUST output your result between these exact delimiters conforming to this schema:", "```json", JSON.stringify(schemaWithoutMeta, null, 2), "```", "", "Example: (Object)", "---RESULT_START---", "{\"key\": \"value\"}", "---RESULT_END---", "", "Example: (String)", "---RESULT_START---", "Hello, world!", "---RESULT_END---");
-	}
-	return parts.join("\n");
-}
-
 //#endregion
 //#region src/result.ts
 /**
@@ -307,26 +332,29 @@ const MAX_EMPTY_POLLS = 60;
 /** Max time to poll before timing out (ms) - 45 minutes. */
 const MAX_POLL_TIME = 2700 * 1e3;
 /**
-* Run a named skill via the OpenCode client and optionally extract a typed result.
+* Low-level primitive: send a fully-formed prompt to OpenCode, poll until
+* idle, and optionally extract a typed result.
+*
+* Both `flu.prompt()` and `flu.skill()` delegate to this function after
+* constructing their own prompt text.
 */
-async function runSkill(client, workdir, name, options) {
-	const { args, result: schema, model, prompt: promptOverride } = options ?? {};
-	const prompt = promptOverride ?? buildSkillPrompt(name, args, schema);
-	console.log(`[flue] skill("${name}"): starting`);
-	console.log(`[flue] skill("${name}"): creating session`);
+async function runPrompt(client, workdir, label, prompt, options) {
+	const { result: schema, model } = options ?? {};
+	console.log(`[flue] ${label}: starting`);
+	console.log(`[flue] ${label}: creating session`);
 	const session = await client.session.create({
-		body: { title: name },
+		body: { title: label },
 		query: { directory: workdir }
 	});
-	console.log(`[flue] skill("${name}"): session created`, {
+	console.log(`[flue] ${label}: session created`, {
 		hasData: !!session.data,
 		sessionId: session.data?.id,
 		error: session.error
 	});
-	if (!session.data) throw new Error(`Failed to create OpenCode session for skill "${name}".`);
+	if (!session.data) throw new Error(`Failed to create OpenCode session for "${label}".`);
 	const sessionId = session.data.id;
 	const promptStart = Date.now();
-	console.log(`[flue] skill("${name}"): sending prompt async`);
+	console.log(`[flue] ${label}: sending prompt async`);
 	const asyncResult = await client.session.promptAsync({
 		path: { id: sessionId },
 		query: { directory: workdir },
@@ -338,31 +366,43 @@ async function runSkill(client, workdir, name, options) {
 			}]
 		}
 	});
-	console.log(`[flue] skill("${name}"): prompt sent`, {
+	console.log(`[flue] ${label}: prompt sent`, {
 		hasError: !!asyncResult.error,
 		error: asyncResult.error,
 		data: asyncResult.data
 	});
-	if (asyncResult.error) throw new Error(`Failed to send prompt for skill "${name}" (session ${sessionId}): ${JSON.stringify(asyncResult.error)}`);
-	await confirmSessionStarted(client, sessionId, workdir, name);
-	console.log(`[flue] skill("${name}"): starting polling`);
-	const parts = await pollUntilIdle(client, sessionId, workdir, name, promptStart);
+	if (asyncResult.error) throw new Error(`Failed to send prompt for "${label}" (session ${sessionId}): ${JSON.stringify(asyncResult.error)}`);
+	await confirmSessionStarted(client, sessionId, workdir, label);
+	console.log(`[flue] ${label}: starting polling`);
+	const parts = await pollUntilIdle(client, sessionId, workdir, label, promptStart);
 	const promptElapsed = ((Date.now() - promptStart) / 1e3).toFixed(1);
-	console.log(`[flue] skill("${name}"): completed (${promptElapsed}s)`);
+	console.log(`[flue] ${label}: completed (${promptElapsed}s)`);
 	if (!schema) return;
 	return extractResult(parts, schema, sessionId);
 }
 /**
+* Run a named skill: builds the skill prompt from the name + args + schema,
+* then delegates to runPrompt().
+*/
+async function runSkill(client, workdir, name, options) {
+	const { args, result: schema, model } = options ?? {};
+	const prompt = buildSkillPrompt(name, args, schema);
+	return runPrompt(client, workdir, `skill("${name}")`, prompt, {
+		result: schema,
+		model
+	});
+}
+/**
 * After promptAsync, confirm that OpenCode actually started processing the session.
 * Polls quickly (1s) to detect the session appearing as "busy" or a user message being recorded.
 * Fails fast (~15s) instead of letting the poll loop run for 5 minutes.
 */
-async function confirmSessionStarted(client, sessionId, workdir, skillName) {
+async function confirmSessionStarted(client, sessionId, workdir, label) {
 	const maxAttempts = 15;
 	for (let attempt = 1; attempt <= maxAttempts; attempt++) {
 		await sleep(1e3);
 		if (((await client.session.status({ query: { directory: workdir } })).data?.[sessionId])?.type === "busy") {
-			console.log(`[flue] skill("${skillName}"): session confirmed running`);
+			console.log(`[flue] ${label}: session confirmed running`);
 			return;
 		}
 		const messages = (await client.session.messages({
@@ -370,20 +410,20 @@ async function confirmSessionStarted(client, sessionId, workdir, skillName) {
 			query: { directory: workdir }
 		})).data;
 		if (messages && messages.length > 0) {
-			console.log(`[flue] skill("${skillName}"): session confirmed (${messages.length} messages)`);
+			console.log(`[flue] ${label}: session confirmed (${messages.length} messages)`);
 			return;
 		}
 	}
-	throw new Error(`Skill "${skillName}" failed to start: session ${sessionId} has no messages after 15s.\nThe prompt was accepted but OpenCode never began processing it.\nThis usually means no model is configured. Pass --model to the flue CLI or set "model" in opencode.json.`);
+	throw new Error(`"${label}" failed to start: session ${sessionId} has no messages after 15s.\nThe prompt was accepted but OpenCode never began processing it.\nThis usually means no model is configured. Pass --model to the flue CLI or set "model" in opencode.json.`);
 }
-async function pollUntilIdle(client, sessionId, workdir, skillName, startTime) {
+async function pollUntilIdle(client, sessionId, workdir, label, startTime) {
 	let emptyPolls = 0;
 	let pollCount = 0;
 	for (;;) {
 		await sleep(POLL_INTERVAL);
 		pollCount++;
 		const elapsed = ((Date.now() - startTime) / 1e3).toFixed(0);
-		if (Date.now() - startTime > MAX_POLL_TIME) throw new Error(`Skill "${skillName}" timed out after ${elapsed}s. Session never went idle. This may indicate a stuck session or OpenCode bug.`);
+		if (Date.now() - startTime > MAX_POLL_TIME) throw new Error(`"${label}" timed out after ${elapsed}s. Session never went idle. This may indicate a stuck session or OpenCode bug.`);
 		const statusResult = await client.session.status({ query: { directory: workdir } });
 		const sessionStatus = statusResult.data?.[sessionId];
 		if (!sessionStatus || sessionStatus.type === "idle") {
@@ -391,31 +431,31 @@ async function pollUntilIdle(client, sessionId, workdir, skillName, startTime) {
 			if (parts.length === 0) {
 				emptyPolls++;
 				if (emptyPolls % 12 === 0) {
-					console.log(`[flue] skill("${skillName}"): status result: ${JSON.stringify({
+					console.log(`[flue] ${label}: status result: ${JSON.stringify({
 						hasData: !!statusResult.data,
 						sessionIds: statusResult.data ? Object.keys(statusResult.data) : [],
 						error: statusResult.error
 					})}`);
-					console.log(`[flue] skill("${skillName}"): sessionStatus for ${sessionId}: ${JSON.stringify(sessionStatus)}`);
+					console.log(`[flue] ${label}: sessionStatus for ${sessionId}: ${JSON.stringify(sessionStatus)}`);
 				}
 				if (emptyPolls >= MAX_EMPTY_POLLS) {
 					const allMessages = await client.session.messages({
 						path: { id: sessionId },
 						query: { directory: workdir }
 					});
-					console.error(`[flue] skill("${skillName}"): TIMEOUT DIAGNOSTICS`, JSON.stringify({
+					console.error(`[flue] ${label}: TIMEOUT DIAGNOSTICS`, JSON.stringify({
 						sessionId,
 						statusData: statusResult.data,
 						messageCount: Array.isArray(allMessages.data) ? allMessages.data.length : 0,
 						messages: allMessages.data
 					}, null, 2));
-					throw new Error(`Skill "${skillName}" produced no output after ${elapsed}s and ${emptyPolls} empty polls. The agent may have failed to start — check model ID and API key.`);
+					throw new Error(`"${label}" produced no output after ${elapsed}s and ${emptyPolls} empty polls. The agent may have failed to start — check model ID and API key.`);
 				}
 				continue;
 			}
 			return parts;
 		}
-		if (pollCount % 12 === 0) console.log(`[flue] skill("${skillName}"): running (${elapsed}s)`);
+		if (pollCount % 12 === 0) console.log(`[flue] ${label}: running (${elapsed}s)`);
 	}
 }
 /**
@@ -471,12 +511,19 @@ var Flue = class {
 		return runSkill(this.client, this.workdir, name, mergedOptions);
 	}
 	async prompt(promptText, options) {
-		const mergedOptions = {
+		const schema = options?.result;
+		const parts = [
+			HEADLESS_PREAMBLE,
+			"",
+			promptText
+		];
+		if (schema) parts.push(buildResultInstructions(schema));
+		const fullPrompt = parts.join("\n");
+		const label = `prompt("${promptText.length > 40 ? promptText.slice(0, 40) + "…" : promptText}")`;
+		return runPrompt(this.client, this.workdir, label, fullPrompt, {
 			result: options?.result,
-			model: options?.model ?? this.model,
-			prompt: promptText
-		};
-		return runSkill(this.client, this.workdir, "__inline__", mergedOptions);
+			model: options?.model ?? this.model
+		});
 	}
 	/** Execute a shell command with scoped environment variables. */
 	async shell(command, options) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@flue/client",
-	"version": "0.0.16",
+	"version": "0.0.18",
 	"type": "module",
 	"license": "Apache-2.0",
 	"exports": {