@clinebot/core 0.0.11 → 0.0.12

package/src/tools/definitions.ts

@@ -38,7 +38,7 @@ import type {
 	EditorExecutor,
 	FileReadExecutor,
 	SearchExecutor,
-	SkillsExecutor,
+	SkillsExecutorWithMetadata,
 	ToolOperationResult,
 	WebFetchExecutor,
 } from "./types.js";
@@ -105,7 +105,7 @@ function normalizeReadFileRequests(input: unknown): ReadFileRequest[] {
 
 function formatReadFileQuery(request: ReadFileRequest): string {
 	const { path, start_line, end_line } = request;
-	if (start_line === undefined && end_line === undefined) {
+	if (start_line == null && end_line == null) {
 		return path;
 	}
 	const start = start_line ?? 1;
@@ -113,63 +113,6 @@ function formatReadFileQuery(request: ReadFileRequest): string {
 	return `${path}:${start}-${end}`;
 }
 
-const APPLY_PATCH_TOOL_DESC = `This is a custom utility that makes it more convenient to add, remove, move, or edit code in a single file. \`apply_patch\` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the \`apply_patch\` command, you should pass a message of the following structure as "input":
-
-%%bash
-apply_patch <<"EOF"
-*** Begin Patch
-[YOUR_PATCH]
-*** End Patch
-EOF
-
-Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.
-
-*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete. 
-
-In a Add File section, every line of the new file (including blank/empty lines) MUST start with a \`+\` prefix. Do not include any unprefixed lines inside an Add section
-In a Update/Delete section, repeat the following for each snippet of code that needs to be changed:
-[context_before] -> See below for further instructions on context.
-- [old_code] -> Precede the old code with a minus sign.
-+ [new_code] -> Precede the new, replacement code with a plus sign.
-[context_after] -> See below for further instructions on context.
-
-For instructions on [context_before] and [context_after]:
-- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
-- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
-@@ class BaseClass
-[3 lines of pre-context]
-- [old_code]
-+ [new_code]
-[3 lines of post-context]
-
-- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple \`@@\` statements to jump to the right context. For instance:
-
-@@ class BaseClass
-@@ 	def method():
-[3 lines of pre-context]
-- [old_code]
-+ [new_code]
-[3 lines of post-context]
-
-Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.
-
-%%bash
-apply_patch <<"EOF"
-*** Begin Patch
-*** Update File: pygorithm/searching/binary_search.py
-@@ class BaseClass
-@@     def search():
--          pass
-+          raise NotImplementedError()
-
-@@ class Subclass
-@@     def search():
--          pass
-+          raise NotImplementedError()
-
-*** End Patch
-EOF`;
-
 // =============================================================================
 // Tool Factory Functions
 // =============================================================================
@@ -404,6 +347,63 @@ export function createWebFetchTool(
 	});
 }
 
+const APPLY_PATCH_TOOL_DESC = `This is a custom utility that makes it more convenient to add, remove, move, or edit code in a single file. \`apply_patch\` effectively allows you to execute a diff/patch against a file, but the format of the diff specification is unique to this task, so pay careful attention to these instructions. To use the \`apply_patch\` command, you should pass a message of the following structure as "input":
+
+%%bash
+apply_patch <<"EOF"
+*** Begin Patch
+[YOUR_PATCH]
+*** End Patch
+EOF
+
+Where [YOUR_PATCH] is the actual content of your patch, specified in the following V4A diff format.
+
+*** [ACTION] File: [path/to/file] -> ACTION can be one of Add, Update, or Delete. 
+
+In a Add File section, every line of the new file (including blank/empty lines) MUST start with a \`+\` prefix. Do not include any unprefixed lines inside an Add section
+In a Update/Delete section, repeat the following for each snippet of code that needs to be changed:
+[context_before] -> See below for further instructions on context.
+- [old_code] -> Precede the old code with a minus sign.
++ [new_code] -> Precede the new, replacement code with a plus sign.
+[context_after] -> See below for further instructions on context.
+
+For instructions on [context_before] and [context_after]:
+- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+- If a code block is repeated so many times in a class or function such that even a single @@ statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple \`@@\` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+Note, then, that we do not use line numbers in this diff format, as the context is enough to uniquely identify code. An example of a message that you might pass as "input" to this function, in order to apply a patch, is shown below.
+
+%%bash
+apply_patch <<"EOF"
+*** Begin Patch
+*** Update File: pygorithm/searching/binary_search.py
+@@ class BaseClass
+@@     def search():
+-          pass
++          raise NotImplementedError()
+
+@@ class Subclass
+@@     def search():
+-          pass
++          raise NotImplementedError()
+
+*** End Patch
+EOF`;
+
 /**
  * Create the apply_patch tool
  *
@@ -470,7 +470,9 @@ export function createEditorTool(
 		description:
 			"An editor for controlled filesystem edits on the text file at the provided path. " +
 			"Provide `insert_line` to insert `new_text` at a specific line number. " +
-			"Otherwise, the tool replaces `old_text` with `new_text`, or creates the file with `new_text` if it does not exist.",
+			"Otherwise, the tool replaces `old_text` with `new_text`, or creates the file with `new_text` if file does not exist. " +
+			"Use this tools for making small, precise edits to existing files or creating new files over shell commands.",
+
 		inputSchema: zodToJsonSchema(EditFileInputSchema),
 		timeoutMs,
 		retryable: false, // Editing operations are stateful and should not auto-retry
@@ -510,21 +512,22 @@ export function createEditorTool(
  * Invokes a configured skill by name and optional arguments.
  */
 export function createSkillsTool(
-	executor: SkillsExecutor,
+	executor: SkillsExecutorWithMetadata,
 	config: Pick<DefaultToolsConfig, "skillsTimeoutMs"> = {},
 ): Tool<SkillsInput, string> {
 	const timeoutMs = config.skillsTimeoutMs ?? 15000;
 
-	return createTool<SkillsInput, string>({
+	const baseDescription =
+		"Execute a skill within the main conversation. " +
+		"When users ask you to perform tasks, check if any available skills match. " +
+		"When users reference a slash command, invoke it with this tool. " +
+		'Input: `skill` (required) and optional `args`. Example: `skill: "pdf"`, `skill: "commit", args: "-m \\"Fix bug\\""`, `skill: "review-pr", args: "123"`, `skill: "ms-office-suite:pdf"`. ' +
+		"When a skill matches the user's request, invoking this tool is a blocking requirement before any other response. " +
+		"Never mention a skill without invoking this tool.";
+
+	const tool = createTool<SkillsInput, string>({
 		name: "skills",
-		description:
-			"Execute a skill within the main conversation. " +
-			"When users ask you to perform tasks, check if any available skills match. " +
-			'When users reference a slash command (for example "/commit" or "/review-pr"), invoke this tool. ' +
-			'Input: `skill` (required) and optional `args`. Example: `skill: "pdf"`, `skill: "commit", args: "-m \\"Fix bug\\""`, `skill: "review-pr", args: "123"`, `skill: "ms-office-suite:pdf"`. ' +
-			"Available skills are listed in system-reminder messages in the conversation. " +
-			"When a skill matches the user's request, invoking this tool is a blocking requirement before any other response. " +
-			"Never mention a skill without invoking this tool.",
+		description: baseDescription,
 		inputSchema: zodToJsonSchema(SkillsInputSchema),
 		timeoutMs,
 		retryable: false,
@@ -542,6 +545,22 @@ export function createSkillsTool(
 			);
 		},
 	});
+
+	Object.defineProperty(tool, "description", {
+		get() {
+			const skills = executor.configuredSkills
+				?.filter((s) => !s.disabled)
+				.map((s) => s.name);
+			if (skills && skills.length > 0) {
+				return `${baseDescription} Available skills: ${skills.join(", ")}.`;
+			}
+			return baseDescription;
+		},
+		enumerable: true,
+		configurable: true,
+	});
+
+	return tool;
 }
 
 /**

package/src/tools/presets.test.ts

@@ -11,10 +11,10 @@ describe("default tool presets", () => {
 		expect(ToolPresets.development.enableAskQuestion).toBe(true);
 		expect(ToolPresets.readonly.enableAskQuestion).toBe(true);
 		expect(ToolPresets.minimal.enableAskQuestion).toBe(true);
-		expect(ToolPresets.yolo.enableAskQuestion).toBe(true);
+		expect(ToolPresets.yolo.enableAskQuestion).toBe(false);
 	});
 
-	it("yolo preset enables all default tools when executors exist", () => {
+	it("yolo preset excludes ask_question even when its executor exists", () => {
 		const tools = createDefaultToolsWithPreset("yolo", {
 			executors: {
 				readFile: async () => "ok",
@@ -35,7 +35,6 @@ describe("default tool presets", () => {
 			"fetch_web_content",
 			"editor",
 			"skills",
-			"ask_question",
 		]);
 	});
 });

package/src/tools/presets.ts

@@ -88,7 +88,7 @@ export const ToolPresets = {
 	},
 
 	/**
-	 * YOLO mode (everything enabled + no approval required)
+	 * YOLO mode (automation-focused tools + no approval required)
 	 * Good for trusted local automation workflows.
 	 */
 	yolo: {
@@ -99,7 +99,7 @@ export const ToolPresets = {
 		enableApplyPatch: false,
 		enableEditor: true,
 		enableSkills: true,
-		enableAskQuestion: true,
+		enableAskQuestion: false,
 	},
 } as const satisfies Record<string, DefaultToolsConfig>;
 
@@ -115,7 +115,7 @@ export type ToolPolicyPresetName = "default" | "yolo";
 
 /**
  * Build tool policies for a preset.
- * `yolo` guarantees all tools are enabled and auto-approved.
+ * `yolo` guarantees tool policies are enabled and auto-approved.
  */
 export function createToolPoliciesWithPreset(
 	presetName: ToolPolicyPresetName,

package/src/tools/schemas.ts

@@ -20,20 +20,24 @@ export const ReadFileLineRangeSchema = z
 			.number()
 			.int()
 			.positive()
+			.nullable()
 			.optional()
-			.describe("Optional one-based starting line number to read from"),
+			.describe(
+				"Optional one-based starting line number to read from; use null or omit for the start of the file",
+			),
 		end_line: z
 			.number()
 			.int()
 			.positive()
+			.nullable()
 			.optional()
-			.describe("Optional one-based ending line number to read through"),
+			.describe(
+				"Optional one-based ending line number to read through; use null or omit for the end of the file",
+			),
 	})
 	.refine(
 		({ start_line, end_line }) =>
-			start_line === undefined ||
-			end_line === undefined ||
-			start_line <= end_line,
+			start_line == null || end_line == null || start_line <= end_line,
 		{
 			message: "start_line must be less than or equal to end_line",
 			path: ["end_line"],
@@ -48,9 +52,7 @@ export const ReadFileRequestSchema = z
 	})
 	.refine(
 		({ start_line, end_line }) =>
-			start_line === undefined ||
-			end_line === undefined ||
-			start_line <= end_line,
+			start_line == null || end_line == null || start_line <= end_line,
 		{
 			message: "start_line must be less than or equal to end_line",
 			path: ["end_line"],
@@ -64,7 +66,7 @@ export const ReadFilesInputSchema = z.object({
 	files: z
 		.array(ReadFileRequestSchema)
 		.describe(
-			"Array of file read requests. Omit start_line and end_line to return the full file content; provide them to return only that inclusive one-based line range. Prefer this tool over running terminal command to get file content for better performance and reliability.",
+			"Array of file read requests. Omit start_line/end_line or set them to null to return the full file content boundaries; provide integers to return only that inclusive one-based line range. Prefer this tool over running terminal command to get file content for better performance and reliability.",
 		),
 });
 
@@ -176,18 +178,22 @@ export const EditFileInputSchema = z
 			),
 	})
 	.describe(
-		"Edit a text file by replacing old_text with new_text, create the file with new_text if it does not exist, or insert new_text at insert_line when insert_line is provided. IMPORTANT: large edits can time out, so use small chunks and multiple calls when possible.",
+		"Edit a text file by replacing old_text with new_text, create the file with new_text if it does not exist, or insert new_text at insert_line when insert_line is provided. Prefer using this tool for file edits over shell commands. IMPORTANT: large edits can time out, so use small chunks and multiple calls when possible.",
 	);
 
 /**
  * Schema for apply_patch tool input
  */
-export const ApplyPatchInputSchema = z.object({
-	input: z
-		.string()
-		.min(1)
-		.describe("The apply_patch text payload, including patch instructions"),
-});
+export const ApplyPatchInputSchema = z
+	.object({
+		input: z
+			.string()
+			.min(1)
+			.describe("The apply_patch text payload, including patch instructions"),
+	})
+	.describe(
+		"Modify or create a text file by applying patches. Prefer using this tool for file edits over shell commands. IMPORTANT: large patches can time out, so use small chunks and multiple calls when possible.",
+	);
 export const ApplyPatchInputUnionSchema = z.union([
 	ApplyPatchInputSchema,
 	z.string(),
@@ -197,12 +203,7 @@ export const ApplyPatchInputUnionSchema = z.union([
  * Schema for skills tool input
  */
 export const SkillsInputSchema = z.object({
-	skill: z
-		.string()
-		.min(1)
-		.describe(
-			'The skill name. E.g., "commit", "review-pr", "pdf", or "ms-office-suite:pdf"',
-		),
+	skill: z.string().min(1).describe("Name of the skill to execute."),
 	args: z
 		.string()
 		.nullable()

package/src/types/config.ts

@@ -76,4 +76,9 @@ export interface CoreSessionConfig
 		| Promise<ConsecutiveMistakeLimitDecision>
 		| ConsecutiveMistakeLimitDecision;
 	toolRoutingRules?: ToolRoutingRule[];
+	/**
+	 * Optional skill allowlist for the `skills` tool. When provided, only these
+	 * skills are surfaced in tool metadata and invocable by name.
+	 */
+	skills?: string[];
 }

package/src/types/events.ts

@@ -36,6 +36,24 @@ export interface SessionTeamProgressEvent {
 	summary: import("@clinebot/shared").TeamProgressSummary;
 }
 
+export interface SessionPendingPromptsEvent {
+	sessionId: string;
+	prompts: Array<{
+		id: string;
+		prompt: string;
+		delivery: "queue" | "steer";
+		attachmentCount: number;
+	}>;
+}
+
+export interface SessionPendingPromptSubmittedEvent {
+	sessionId: string;
+	id: string;
+	prompt: string;
+	delivery: "queue" | "steer";
+	attachmentCount: number;
+}
+
 export type CoreSessionEvent =
 	| { type: "chunk"; payload: SessionChunkEvent }
 	| {
@@ -46,6 +64,11 @@ export type CoreSessionEvent =
 			};
 	  }
 	| { type: "team_progress"; payload: SessionTeamProgressEvent }
+	| { type: "pending_prompts"; payload: SessionPendingPromptsEvent }
+	| {
+			type: "pending_prompt_submitted";
+			payload: SessionPendingPromptSubmittedEvent;
+	  }
 	| { type: "ended"; payload: SessionEndedEvent }
 	| { type: "hook"; payload: SessionToolEvent }
 	| { type: "status"; payload: { sessionId: string; status: string } };