pi-mono-all 1.2.3 → 1.2.5

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # pi-mono-all
 
+## 1.2.5
+
+### Patch Changes
+
+- Bundle `pi-mono-linear@0.2.4` with automatic Markdown description image reading for `linear_get_issue` on vision-capable models.
+
+## 1.2.4
+
+### Patch Changes
+
+- Bundle `pi-mono-sentinel@1.12.0` with project-scoped config stored under the Pi agent directory instead of the current working directory.
+
 ## 1.2.3
 
 ### Patch Changes

package/node_modules/pi-mono-linear/CHANGELOG.md

@@ -1,5 +1,11 @@
 # pi-mono-linear
 
+## 0.2.4
+
+### Patch Changes
+
+- Added automatic Markdown description image reading to `linear_get_issue` for vision-capable models. Private `uploads.linear.app` images are streamed in memory with Linear auth and attached as native image blocks; text-only models skip downloads with a clear note.
+
 ## 0.2.3
 
 ### Patch Changes

package/node_modules/pi-mono-linear/README.md

@@ -132,11 +132,28 @@ Linear API keys are sent in the `Authorization` header as the raw key value; do
 - `linear_create_issue` accepts either a team UUID or a team key; keys are resolved to UUIDs before the Linear mutation.
 - Use `linear_search_issues` for keyword lookup.
 - Use `linear_get_issue` before updating an issue or creating a comment.
+- `linear_get_issue` automatically parses Markdown images embedded in the issue description. When the active model supports image input, private `uploads.linear.app` images are downloaded in memory with Linear auth and attached to the tool result; images are not written to disk.
+- If the active model does not support image input, `linear_get_issue` does not download images and returns a clear skipped-images note plus image metadata.
 - Use `linear_list_issues` for filtered issue lists by team, assignee, status, and limit.
 - Use `linear_upload_file` to upload a local image, video, or generic file and return a Linear asset URL.
 - Use `linear_upload_file_to_issue_comment` after `linear_get_issue` to upload a local file and post a Markdown comment. Images are rendered with image Markdown; other files use links.
 - File upload tool results return sanitized metadata and the stable Linear asset URL. They do not return local file bytes, signed upload URLs, or upload headers.
 
+## Issue description images
+
+Linear issue screenshots embedded in descriptions are stored as Markdown image links, for example:
+
+```md
+![Screenshot](https://uploads.linear.app/...)
+```
+
+These are part of the issue description Markdown, not GraphQL attachment objects. `linear_get_issue` reads them automatically when possible:
+
+- Vision-capable model: images are streamed into memory, base64-encoded, and returned as native image blocks alongside the Markdown description.
+- Text-only model: image downloads are skipped to avoid unnecessary network and payload work; the response includes a note explaining that a vision-capable model is required.
+- No files are saved locally by default.
+- The default safety limits are 10 description images and 10 MiB per image.
+
 ## Troubleshooting
 
 ### Missing auth key

package/node_modules/pi-mono-linear/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mono-linear",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Pi extension and skill for Linear GraphQL tools",
   "type": "module",
   "keywords": [

package/node_modules/pi-mono-linear/skills/linear/SKILL.md

@@ -27,6 +27,8 @@ If auth is missing, invalid, or expired, do **not** ask the user to paste the ke
 - Use `linear_workspace_metadata` first when team/project/state/label/user IDs are unknown.
 - Use `linear_search_issues` for keyword lookup.
 - Use `linear_get_issue` before updating or commenting.
+- Use `linear_get_issue` to inspect Linear issues; Markdown images embedded in the issue description are automatically included when the active model supports image input.
+- If `linear_get_issue` reports description images were skipped because the current model does not support images, ask the user to switch to a vision-capable model before interpreting screenshots.
 - Use `linear_list_issues` for filtered issue lists by team, assignee, status, or limit.
 - Use `linear_create_issue` to create issues once the team ID is known.
 - Use `linear_update_issue` to change title, description, priority, state, or assignee.
@@ -76,6 +78,14 @@ If auth is missing, invalid, or expired, do **not** ask the user to paste the ke
 - `linear_upload_file`
 - `linear_upload_file_to_issue_comment`
 
+## Issue Description Images
+
+- Linear issue screenshots embedded in descriptions are Markdown images, not necessarily GraphQL attachment objects.
+- `linear_get_issue` parses description Markdown image links like `![Screenshot](https://uploads.linear.app/...)`.
+- When the active model supports image input, `linear_get_issue` downloads private Linear image URLs in memory with Linear auth and attaches native image blocks to the result.
+- When the active model is text-only, image downloads are skipped and the tool returns a note plus image metadata.
+- Description images are not written to disk by default.
+
 ## File Upload Notes
 
 - Upload tools accept local file paths only; they do not read folders recursively.

package/node_modules/pi-mono-linear/src/linear-client.ts

@@ -5,6 +5,7 @@ import { createHttpClient, type HttpClient } from "pi-common/http-client";
 import { createRateLimiter, type RateLimiter } from "pi-common/rate-limiter";
 import { readFile, stat } from "node:fs/promises";
 import { basename, extname, resolve } from "node:path";
+import type { MarkdownImageReference } from "./linear-markdown-images.js";
 import * as queries from "./linear-queries.js";
 
 export interface LinearClientOptions {
@@ -46,6 +47,20 @@ export interface UploadFileInput {
 	makePublic?: boolean;
 }
 
+export interface DownloadIssueImageInput {
+	reference: MarkdownImageReference;
+	maxBytes?: number;
+	signal?: AbortSignal;
+}
+
+export interface DownloadedIssueImageResult {
+	reference: MarkdownImageReference;
+	filename: string;
+	mimeType: string;
+	size: number;
+	data: string;
+}
+
 interface UploadFileHeader {
 	key: string;
 	value: string;
@@ -98,6 +113,8 @@ interface GraphQlResponse<T> {
 
 const cache = createTtlCache<unknown>({ defaultTtlMs: 60_000, maxEntries: 100 });
 const DEFAULT_MAX_UPLOAD_BYTES = 50 * 1024 * 1024;
+const DEFAULT_MAX_DOWNLOAD_IMAGE_BYTES = 10 * 1024 * 1024;
+const SUPPORTED_INLINE_IMAGE_TYPES = new Set(["image/png", "image/jpeg", "image/webp", "image/gif"]);
 
 export class LinearClient {
 	private readonly http: HttpClient;
@@ -224,6 +241,10 @@ export class LinearClient {
 		};
 	}
 
+	async downloadIssueImage(input: DownloadIssueImageInput): Promise<DownloadedIssueImageResult> {
+		return downloadIssueImage(input);
+	}
+
 	listCycles(teamId?: string): Promise<unknown> {
 		return teamId
 			? this.cached(`teamCycles:${teamId}`, () => this.graphql(queries.LIST_TEAM_CYCLES, { id: teamId }))
@@ -344,6 +365,131 @@ async function safeUploadBody(response: Response): Promise<unknown> {
 	}
 }
 
+async function downloadIssueImage(input: DownloadIssueImageInput): Promise<DownloadedIssueImageResult> {
+	const url = validateLinearImageUrl(input.reference.url);
+	const maxBytes = input.maxBytes ?? DEFAULT_MAX_DOWNLOAD_IMAGE_BYTES;
+	if (!Number.isFinite(maxBytes) || maxBytes <= 0) {
+		throw new ApiError("maxImageBytes must be a positive number", 400, { maxBytes }, "Linear");
+	}
+
+	const token = await readLinearToken();
+	const response = await downloadLinearFile(url, token, input.signal);
+	if (!response.ok) {
+		throw new ApiError(response.statusText || `Image download failed with HTTP ${response.status}`, response.status, await safeUploadBody(response), "Linear");
+	}
+	if (!response.body) {
+		throw new ApiError("Image download response did not include a body", 502, { url }, "Linear");
+	}
+
+	const contentLength = response.headers.get("content-length");
+	if (contentLength && Number(contentLength) > maxBytes) {
+		throw new ApiError(`Image is too large (${contentLength} bytes). Limit is ${maxBytes} bytes.`, 400, { size: Number(contentLength), maxBytes }, "Linear");
+	}
+
+	const bytes = await readResponseBytes(response.body, maxBytes);
+	const mimeType = detectSupportedImageMimeType(bytes, response.headers.get("content-type"));
+	if (!mimeType) {
+		throw new ApiError("Downloaded file is not a supported inline image", 415, { contentType: response.headers.get("content-type"), supportedTypes: [...SUPPORTED_INLINE_IMAGE_TYPES] }, "Linear");
+	}
+
+	return {
+		reference: input.reference,
+		filename: filenameForImageUrl(url, mimeType, input.reference.index),
+		mimeType,
+		size: bytes.byteLength,
+		data: Buffer.from(bytes).toString("base64"),
+	};
+}
+
+async function downloadLinearFile(url: string, token: string, signal?: AbortSignal): Promise<Response> {
+	const normalizedToken = token.replace(/^Bearer\s+/i, "").trim();
+	const rawResponse = await fetch(url, { method: "GET", headers: { Authorization: normalizedToken }, signal });
+	if (rawResponse.status !== 401 && rawResponse.status !== 403) return rawResponse;
+
+	// Linear personal API keys use `Authorization: <API_KEY>`, while OAuth access
+	// tokens use `Authorization: Bearer <ACCESS_TOKEN>`. The extension normally
+	// stores personal API keys, but this fallback keeps file reads compatible with
+	// OAuth-style tokens without requiring a separate auth configuration.
+	await rawResponse.body?.cancel().catch(() => undefined);
+	return fetch(url, { method: "GET", headers: { Authorization: `Bearer ${normalizedToken}` }, signal });
+}
+
+function validateLinearImageUrl(value: string): string {
+	let url: URL;
+	try {
+		url = new URL(value);
+	} catch {
+		throw new ApiError("Invalid image URL in Linear issue description", 400, { url: value }, "Linear");
+	}
+	if (url.protocol !== "https:") {
+		throw new ApiError("Only HTTPS Linear image URLs are supported", 400, { url: value }, "Linear");
+	}
+	if (url.hostname !== "uploads.linear.app") {
+		throw new ApiError("Only uploads.linear.app issue description images are supported", 400, { url: value, hostname: url.hostname }, "Linear");
+	}
+	return url.toString();
+}
+
+async function readResponseBytes(body: ReadableStream<Uint8Array>, maxBytes: number): Promise<Uint8Array> {
+	const reader = body.getReader();
+	const chunks: Uint8Array[] = [];
+	let total = 0;
+	try {
+		while (true) {
+			const { done, value } = await reader.read();
+			if (done) break;
+			if (!value) continue;
+			total += value.byteLength;
+			if (total > maxBytes) {
+				throw new ApiError(`Image is too large. Limit is ${maxBytes} bytes.`, 400, { size: total, maxBytes }, "Linear");
+			}
+			chunks.push(value);
+		}
+	} finally {
+		reader.releaseLock();
+	}
+	return Buffer.concat(chunks, total);
+}
+
+function detectSupportedImageMimeType(bytes: Uint8Array, contentType: string | null): string | undefined {
+	const magic = detectImageMimeTypeFromMagicBytes(bytes);
+	if (magic && SUPPORTED_INLINE_IMAGE_TYPES.has(magic)) return magic;
+
+	const normalized = contentType?.split(";")[0]?.trim().toLowerCase();
+	if (normalized && SUPPORTED_INLINE_IMAGE_TYPES.has(normalized)) return normalized;
+	return undefined;
+}
+
+function detectImageMimeTypeFromMagicBytes(bytes: Uint8Array): string | undefined {
+	if (bytes.length >= 8 && bytes[0] === 0x89 && bytes[1] === 0x50 && bytes[2] === 0x4e && bytes[3] === 0x47 && bytes[4] === 0x0d && bytes[5] === 0x0a && bytes[6] === 0x1a && bytes[7] === 0x0a) return "image/png";
+	if (bytes.length >= 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return "image/jpeg";
+	if (bytes.length >= 6) {
+		const signature = Buffer.from(bytes.slice(0, 6)).toString("ascii");
+		if (signature === "GIF87a" || signature === "GIF89a") return "image/gif";
+	}
+	if (bytes.length >= 12) {
+		const riff = Buffer.from(bytes.slice(0, 4)).toString("ascii");
+		const webp = Buffer.from(bytes.slice(8, 12)).toString("ascii");
+		if (riff === "RIFF" && webp === "WEBP") return "image/webp";
+	}
+	return undefined;
+}
+
+function filenameForImageUrl(url: string, mimeType: string, index: number): string {
+	const pathname = new URL(url).pathname;
+	const leaf = basename(pathname);
+	const extension = extensionForMimeType(mimeType);
+	if (leaf && leaf.includes(".")) return leaf;
+	return `linear-description-image-${index}.${extension}`;
+}
+
+function extensionForMimeType(mimeType: string): string {
+	if (mimeType === "image/jpeg") return "jpg";
+	if (mimeType === "image/webp") return "webp";
+	if (mimeType === "image/gif") return "gif";
+	return "png";
+}
+
 function inferContentType(filePath: string): string {
 	const extension = extname(filePath).toLowerCase();
 	return CONTENT_TYPES[extension] ?? "application/octet-stream";

package/node_modules/pi-mono-linear/src/linear-markdown-images.ts

@@ -0,0 +1,91 @@
+export interface MarkdownImageReference {
+	index: number;
+	source: "description";
+	altText: string;
+	url: string;
+	rawMarkdown: string;
+	line: number;
+	start: number;
+	end: number;
+	contextSnippet: string;
+}
+
+export interface ExtractMarkdownImagesOptions {
+	source?: MarkdownImageReference["source"];
+	contextLines?: number;
+}
+
+const MARKDOWN_IMAGE_RE = /!\[([^\]]*)\]\(\s*(<[^>]+>|[^\s)]+)(?:\s+["'][^"']*["'])?\s*\)/g;
+
+export function extractMarkdownImages(markdown: string, options: ExtractMarkdownImagesOptions = {}): MarkdownImageReference[] {
+	const source = options.source ?? "description";
+	const contextLines = options.contextLines ?? 2;
+	const lineStarts = getLineStarts(markdown);
+	const lines = markdown.split("\n");
+	const references: MarkdownImageReference[] = [];
+
+	for (const match of markdown.matchAll(MARKDOWN_IMAGE_RE)) {
+		const rawMarkdown = match[0];
+		const rawUrl = match[2] ?? "";
+		const url = unwrapMarkdownUrl(rawUrl);
+		if (!url) continue;
+
+		const start = match.index ?? 0;
+		const end = start + rawMarkdown.length;
+		const line = lineForOffset(lineStarts, start);
+		references.push({
+			index: references.length + 1,
+			source,
+			altText: unescapeMarkdownText(match[1] ?? ""),
+			url,
+			rawMarkdown,
+			line,
+			start,
+			end,
+			contextSnippet: buildContextSnippet(lines, line, contextLines),
+		});
+	}
+
+	return references;
+}
+
+function unwrapMarkdownUrl(rawUrl: string): string {
+	const trimmed = rawUrl.trim();
+	if (trimmed.startsWith("<") && trimmed.endsWith(">")) return trimmed.slice(1, -1).trim();
+	return trimmed;
+}
+
+function unescapeMarkdownText(value: string): string {
+	return value.replace(/\\([\\\[\]])/g, "$1");
+}
+
+function getLineStarts(text: string): number[] {
+	const starts = [0];
+	for (let index = 0; index < text.length; index++) {
+		if (text[index] === "\n") starts.push(index + 1);
+	}
+	return starts;
+}
+
+function lineForOffset(lineStarts: number[], offset: number): number {
+	let low = 0;
+	let high = lineStarts.length - 1;
+	while (low <= high) {
+		const mid = Math.floor((low + high) / 2);
+		const start = lineStarts[mid] ?? 0;
+		const next = lineStarts[mid + 1] ?? Number.POSITIVE_INFINITY;
+		if (offset >= start && offset < next) return mid + 1;
+		if (offset < start) high = mid - 1;
+		else low = mid + 1;
+	}
+	return lineStarts.length;
+}
+
+function buildContextSnippet(lines: string[], line: number, contextLines: number): string {
+	const start = Math.max(1, line - contextLines);
+	const end = Math.min(lines.length, line + contextLines);
+	return lines
+		.slice(start - 1, end)
+		.map((text, index) => `${start + index}: ${text}`)
+		.join("\n");
+}

package/node_modules/pi-mono-linear/src/linear-schemas.ts

@@ -15,7 +15,13 @@ export const OptionalTeamParams = Type.Object({ teamId: Type.Optional(TeamIdSche
 export const IdParams = Type.Object({ id: Type.String({ description: "Linear object ID" }), maxResponseChars: MaxResponseCharsSchema });
 
 export const LinearGetTeamParams = Type.Object({ teamId: TeamIdSchema, maxResponseChars: MaxResponseCharsSchema });
-export const LinearGetIssueParams = Type.Object({ issueId: IssueIdSchema, maxResponseChars: MaxResponseCharsSchema });
+export const LinearGetIssueParams = Type.Object({
+	issueId: IssueIdSchema,
+	readDescriptionImages: Type.Optional(Type.Boolean({ description: "Read Markdown images embedded in the issue description when the active model supports image input. Defaults to true." })),
+	maxDescriptionImages: Type.Optional(Type.Number({ description: "Maximum number of description images to read. Defaults to 10.", minimum: 1, maximum: 50 })),
+	maxImageBytes: Type.Optional(Type.Number({ description: "Maximum bytes per description image before download is stopped. Defaults to 10 MiB.", minimum: 1 })),
+	maxResponseChars: MaxResponseCharsSchema,
+});
 export const LinearGetProjectParams = Type.Object({ projectId: ProjectIdSchema, maxResponseChars: MaxResponseCharsSchema });
 export const LinearGetUserParams = Type.Object({ userId: UserIdSchema, maxResponseChars: MaxResponseCharsSchema });
 export const LinearGetDocumentParams = Type.Object({ documentId: Type.String({ description: "Linear document UUID" }), maxResponseChars: MaxResponseCharsSchema });

package/node_modules/pi-mono-linear/src/linear-tools.ts

@@ -1,7 +1,8 @@
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { registerAuthConfigurator, runWithAuthRetry, type AuthConfiguratorOptions } from "pi-common/auth-config";
 import { jsonToolResult } from "pi-common/tool-result";
-import { LinearClient, type UploadedFileResult } from "./linear-client.js";
+import { LinearClient, type DownloadedIssueImageResult, type UploadedFileResult } from "./linear-client.js";
+import { extractMarkdownImages, type MarkdownImageReference } from "./linear-markdown-images.js";
 import {
 	EmptyParams,
 	LinearCommentsParams,
@@ -23,6 +24,30 @@ import {
 	OptionalTeamParams,
 } from "./linear-schemas.js";
 
+type LinearToolContent = { type: "text"; text: string } | { type: "image"; data: string; mimeType: string };
+
+interface DescriptionImageManifestEntry {
+	index: number;
+	source: "description";
+	altText: string;
+	url: string;
+	line: number;
+	contextSnippet: string;
+	status: "downloaded" | "skipped";
+	mimeType?: string;
+	size?: number;
+	filename?: string;
+	reason?: string;
+}
+
+interface LinearIssueNodeLike {
+	id?: string;
+	identifier?: string;
+	title?: string;
+	url?: string;
+	description?: string | null;
+}
+
 const LINEAR_AUTH: AuthConfiguratorOptions = {
 	service: "linear",
 	displayName: "Linear",
@@ -57,6 +82,139 @@ function escapeMarkdownAltText(value: string): string {
 	return value.replaceAll("[", "\\[").replaceAll("]", "\\]");
 }
 
+function getIssueNode(result: unknown): LinearIssueNodeLike | undefined {
+	if (!result || typeof result !== "object") return undefined;
+	const issue = (result as { issue?: unknown }).issue;
+	if (!issue || typeof issue !== "object") return undefined;
+	return issue as LinearIssueNodeLike;
+}
+
+function modelSupportsImages(ctx: ExtensionContext): boolean {
+	return ctx.model?.input?.includes("image") ?? false;
+}
+
+function buildSkippedManifestEntry(reference: MarkdownImageReference, reason: string): DescriptionImageManifestEntry {
+	return {
+		index: reference.index,
+		source: reference.source,
+		altText: reference.altText,
+		url: reference.url,
+		line: reference.line,
+		contextSnippet: reference.contextSnippet,
+		status: "skipped",
+		reason,
+	};
+}
+
+function buildDownloadedManifestEntry(image: DownloadedIssueImageResult): DescriptionImageManifestEntry {
+	return {
+		index: image.reference.index,
+		source: image.reference.source,
+		altText: image.reference.altText,
+		url: image.reference.url,
+		line: image.reference.line,
+		contextSnippet: image.reference.contextSnippet,
+		status: "downloaded",
+		mimeType: image.mimeType,
+		size: image.size,
+		filename: image.filename,
+	};
+}
+
+function errorMessage(error: unknown): string {
+	return error instanceof Error ? error.message : String(error);
+}
+
+function appendImageReadingMetadata(result: unknown, imageReading: unknown): unknown {
+	if (!result || typeof result !== "object" || Array.isArray(result)) return { result, imageReading };
+	return { ...(result as Record<string, unknown>), imageReading };
+}
+
+function issueLabel(issue: LinearIssueNodeLike | undefined): string {
+	if (!issue) return "Linear issue";
+	return [issue.identifier, issue.title].filter(Boolean).join(" — ") || issue.id || "Linear issue";
+}
+
+function imageNote(reference: MarkdownImageReference, image: DownloadedIssueImageResult): string {
+	return [
+		`[Description image ${reference.index}: alt=${JSON.stringify(reference.altText || "image")}, line=${reference.line}, mimeType=${image.mimeType}, size=${image.size} bytes]`,
+		"Markdown context:",
+		reference.contextSnippet,
+	].join("\n");
+}
+
+async function buildIssueResultWithDescriptionImages(options: {
+	client: LinearClient;
+	result: unknown;
+	ctx: ExtensionContext;
+	readDescriptionImages?: boolean;
+	maxDescriptionImages?: number;
+	maxImageBytes?: number;
+	maxResponseChars?: number;
+	signal?: AbortSignal;
+}): Promise<{ content: LinearToolContent[]; details: Record<string, unknown> }> {
+	const issue = getIssueNode(options.result);
+	const description = issue?.description ?? "";
+	const references = typeof description === "string" ? extractMarkdownImages(description, { source: "description" }) : [];
+	const shouldReadImages = options.readDescriptionImages ?? true;
+	if (!references.length || !shouldReadImages) {
+		return jsonToolResult(options.result, { maxChars: options.maxResponseChars });
+	}
+
+	const maxImages = options.maxDescriptionImages ?? 10;
+	const selected = references.slice(0, maxImages);
+	const overflow = references.slice(maxImages);
+	const supportsImages = modelSupportsImages(options.ctx);
+	const manifest: DescriptionImageManifestEntry[] = [];
+	const imageContents: LinearToolContent[] = [];
+
+	if (!supportsImages) {
+		manifest.push(...references.map((reference) => buildSkippedManifestEntry(reference, "model_does_not_support_images")));
+		const note = `Description images detected but not downloaded because the current model does not support image input. Switch to a vision-capable model to inspect them.`;
+		const data = appendImageReadingMetadata(options.result, {
+			modelSupportsImages: false,
+			descriptionImagesFound: references.length,
+			descriptionImages: manifest,
+			note,
+		});
+		const base = jsonToolResult(data, { maxChars: options.maxResponseChars });
+		return {
+			content: [...base.content, { type: "text", text: `\n[${note}]` }],
+			details: { ...base.details, imageReading: { issue: issue ? { id: issue.id, identifier: issue.identifier, title: issue.title, url: issue.url } : undefined, descriptionImages: manifest } },
+		};
+	}
+
+	for (const reference of selected) {
+		try {
+			const image = await options.client.downloadIssueImage({ reference, maxBytes: options.maxImageBytes, signal: options.signal });
+			manifest.push(buildDownloadedManifestEntry(image));
+			imageContents.push({ type: "text", text: imageNote(reference, image) }, { type: "image", mimeType: image.mimeType, data: image.data });
+		} catch (error) {
+			manifest.push(buildSkippedManifestEntry(reference, errorMessage(error)));
+			imageContents.push({ type: "text", text: `[Description image ${reference.index} skipped: ${errorMessage(error)}]` });
+		}
+	}
+	for (const reference of overflow) {
+		manifest.push(buildSkippedManifestEntry(reference, `maxDescriptionImages limit (${maxImages}) reached`));
+	}
+
+	const data = appendImageReadingMetadata(options.result, {
+		modelSupportsImages: true,
+		descriptionImagesFound: references.length,
+		descriptionImagesRead: manifest.filter((entry) => entry.status === "downloaded").length,
+		descriptionImages: manifest,
+	});
+	const base = jsonToolResult(data, { maxChars: options.maxResponseChars });
+	const preamble: LinearToolContent = {
+		type: "text",
+		text: `\nRead ${manifest.filter((entry) => entry.status === "downloaded").length} of ${references.length} Markdown description image(s) for ${issueLabel(issue)}. Images are attached below in description order.`,
+	};
+	return {
+		content: [...base.content, preamble, ...imageContents],
+		details: { ...base.details, imageReading: { issue: issue ? { id: issue.id, identifier: issue.identifier, title: issue.title, url: issue.url } : undefined, descriptionImages: manifest } },
+	};
+}
+
 export function registerLinearTools(pi: ExtensionAPI): void {
 	const client = new LinearClient();
 	registerAuthConfigurator(pi, LINEAR_AUTH);
@@ -127,10 +285,24 @@ export function registerLinearTools(pi: ExtensionAPI): void {
 	pi.registerTool({
 		name: "linear_get_issue",
 		label: "Linear Get Issue",
-		description: "Get full Linear issue details by UUID or identifier like ENG-123.",
+		description: "Get full Linear issue details by UUID or identifier like ENG-123. Markdown images embedded in the issue description are read and attached when the active model supports image input.",
+		promptGuidelines: [
+			"Use linear_get_issue to inspect Linear issues; if the issue description contains Markdown images and the active model supports image input, the images are downloaded in memory and attached to the tool result.",
+			"When linear_get_issue reports description images were skipped because the model does not support images, ask the user to switch to a vision-capable model before interpreting screenshots.",
+		],
 		parameters: LinearGetIssueParams,
-		async execute(_id, params, _signal, _onUpdate, ctx) {
-			return jsonToolResult(await withLinearAuth(ctx, () => client.getIssue(params.issueId)), { maxChars: params.maxResponseChars });
+		async execute(_id, params, signal, _onUpdate, ctx) {
+			const result = await withLinearAuth(ctx, () => client.getIssue(params.issueId));
+			return buildIssueResultWithDescriptionImages({
+				client,
+				result,
+				ctx,
+				readDescriptionImages: params.readDescriptionImages,
+				maxDescriptionImages: params.maxDescriptionImages,
+				maxImageBytes: params.maxImageBytes,
+				maxResponseChars: params.maxResponseChars,
+				signal,
+			});
 		},
 	});
 

package/node_modules/pi-mono-sentinel/CHANGELOG.md

@@ -1,5 +1,11 @@
 # pi-mono-sentinel
 
+## 1.12.0
+
+### Changed
+
+- Store project-scoped Sentinel config under the Pi agent directory (`~/.pi/agent/extensions/sentinel/projects/`) instead of creating `.pi/extensions/sentinel.json` in the current working directory. Existing cwd-local config files are still read for compatibility.
+
 ## 1.11.0
 
 ### Minor Changes

package/node_modules/pi-mono-sentinel/README.md

@@ -14,11 +14,13 @@ It addresses cross-cutting security gaps that pure command-based guardrails miss
 Sentinel reads and merges optional JSON config from three scopes:
 
 1. Global: `$PI_CODING_AGENT_DIR/extensions/sentinel.json` or `~/.pi/agent/extensions/sentinel.json`
-2. Local/project: `.pi/extensions/sentinel.json` under the current working directory
+2. Local/project: a current-working-directory scoped file under `$PI_CODING_AGENT_DIR/extensions/sentinel/projects/` or `~/.pi/agent/extensions/sentinel/projects/`
 3. Memory: session-only grants written internally while Pi is running
 
 Merge priority is `memory > local > global > defaults`.
 
+Local/project config is stored in Pi's agent directory instead of the user's working directory, so Sentinel does not create `.pi/` files in arbitrary project folders. Existing legacy `.pi/extensions/sentinel.json` files are still read for compatibility, but new local/project writes go to the agent directory.
+
 ```json
 {
   "enabled": true,

package/node_modules/pi-mono-sentinel/__tests__/config.test.ts

@@ -1,7 +1,7 @@
 import assert from "node:assert/strict";
-import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { afterEach, beforeEach, describe, test } from "node:test";
 
 import { SentinelConfigLoader } from "../config.ts";
@@ -39,7 +39,7 @@ describe("SentinelConfigLoader", () => {
 		mkdirSync(join(agentDir, "extensions"), { recursive: true });
 		writeFileSync(loader.getConfigPath("global"), JSON.stringify({ pathAccess: { allowedPaths: ["/global"] } }), { flag: "w" });
 		loader.load(cwd);
-		mkdirSync(join(cwd, ".pi", "extensions"), { recursive: true });
+		mkdirSync(dirname(loader.getConfigPath("local")), { recursive: true });
 		writeFileSync(loader.getConfigPath("local"), JSON.stringify({ features: { pathAccess: true }, pathAccess: { allowedPaths: ["/local"] } }), { flag: "w" });
 		loader.load(cwd);
 		loader.save("memory", { pathAccess: { mode: "block", allowedPaths: ["/memory"] } });
@@ -49,12 +49,26 @@ describe("SentinelConfigLoader", () => {
 		assert.deepEqual(config.pathAccess.allowedPaths, ["/memory"]);
 	});
 
-	test("save writes global and local config files", () => {
+	test("save writes global and cwd-scoped local config files under the agent dir", () => {
 		const loader = new SentinelConfigLoader();
 		loader.load(cwd);
 		loader.save("global", { enabled: false });
 		loader.save("local", { features: { pathAccess: true } });
 		assert.deepEqual(loader.getRawConfig("global"), { enabled: false });
 		assert.deepEqual(loader.getRawConfig("local"), { features: { pathAccess: true } });
+		assert.equal(loader.getConfigPath("local").startsWith(join(agentDir, "extensions", "sentinel", "projects")), true);
+		assert.equal(existsSync(join(cwd, ".pi", "extensions", "sentinel.json")), false);
+	});
+
+	test("reads legacy cwd-local config without writing back to cwd", () => {
+		const loader = new SentinelConfigLoader();
+		mkdirSync(join(cwd, ".pi", "extensions"), { recursive: true });
+		writeFileSync(join(cwd, ".pi", "extensions", "sentinel.json"), JSON.stringify({ features: { pathAccess: true } }), { flag: "w" });
+
+		loader.load(cwd);
+		assert.equal(loader.getConfig().features.pathAccess, true);
+
+		loader.save("local", { pathAccess: { allowedPaths: ["/outside"] } });
+		assert.equal(existsSync(loader.getConfigPath("local")), true);
 	});
 });

package/node_modules/pi-mono-sentinel/__tests__/path-access.test.ts

@@ -44,7 +44,10 @@ describe("path-access helpers", () => {
 	});
 
 	test("derives and persists selected path-access grants with the correct scope and target", () => {
+		const originalAgentDir = process.env.PI_CODING_AGENT_DIR;
+		const agentDir = mkdtempSync(join(tmpdir(), "sentinel-path-access-agent-"));
 		const cwd = mkdtempSync(join(tmpdir(), "sentinel-path-access-cwd-"));
+		process.env.PI_CODING_AGENT_DIR = agentDir;
 		try {
 			configLoader.load(cwd);
 			configLoader.save("memory", { features: { pathAccess: true }, pathAccess: { mode: "ask", allowedPaths: [] } });
@@ -69,6 +72,9 @@ describe("path-access helpers", () => {
 			configLoader.addAllowedPath(localFileGrant.scope, localFileGrant.grant);
 			assert.ok(configLoader.getRawConfig("local")?.pathAccess?.allowedPaths?.includes("/tmp/outside-file.txt"));
 		} finally {
+			if (originalAgentDir === undefined) delete process.env.PI_CODING_AGENT_DIR;
+			else process.env.PI_CODING_AGENT_DIR = originalAgentDir;
+			rmSync(agentDir, { recursive: true, force: true });
 			rmSync(cwd, { recursive: true, force: true });
 		}
 	});

package/node_modules/pi-mono-sentinel/config.ts

@@ -1,6 +1,7 @@
+import { createHash } from "node:crypto";
 import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
-import { dirname, join } from "node:path";
+import { basename, dirname, join, resolve } from "node:path";
 
 export type SentinelConfigScope = "global" | "local" | "memory";
 export type SentinelPathAccessMode = "allow" | "ask" | "block";
@@ -92,6 +93,20 @@ function writeJson(path: string, value: SentinelConfig): void {
 	writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`, "utf-8");
 }
 
+function localScopeId(cwd: string): string {
+	const normalizedCwd = resolve(cwd);
+	const slug = (basename(normalizedCwd) || "root")
+		.replace(/[^a-zA-Z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "")
+		.slice(0, 48) || "root";
+	const hash = createHash("sha256").update(normalizedCwd).digest("hex").slice(0, 12);
+	return `${slug}-${hash}.json`;
+}
+
+function legacyLocalConfigPath(cwd: string): string {
+	return join(resolve(cwd), ".pi", "extensions", "sentinel.json");
+}
+
 function isPlainObject(value: unknown): value is Record<string, unknown> {
 	return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -127,7 +142,11 @@ export class SentinelConfigLoader {
 	load(cwd = process.cwd()): void {
 		this.localCwd = cwd;
 		this.globalConfig = readJson(this.getConfigPath("global"));
-		this.localConfig = readJson(this.getConfigPath("local"));
+		const legacyLocalConfig = readJson(legacyLocalConfigPath(this.localCwd));
+		const scopedLocalConfig = readJson(this.getConfigPath("local"));
+		this.localConfig = legacyLocalConfig && scopedLocalConfig
+			? mergeConfig(legacyLocalConfig, scopedLocalConfig)
+			: scopedLocalConfig ?? legacyLocalConfig;
 		this.resolvedConfig = undefined;
 	}
 
@@ -152,7 +171,7 @@ export class SentinelConfigLoader {
 	getConfigPath(scope: Exclude<SentinelConfigScope, "memory">): string {
 		return scope === "global"
 			? join(getAgentDir(), "extensions", "sentinel.json")
-			: join(this.localCwd, ".pi", "extensions", "sentinel.json");
+			: join(getAgentDir(), "extensions", "sentinel", "projects", localScopeId(this.localCwd));
 	}
 
 	save(scope: SentinelConfigScope, partial: SentinelConfig): void {

package/node_modules/pi-mono-sentinel/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mono-sentinel",
-  "version": "1.11.0",
+  "version": "1.12.0",
   "description": "Pi extension that guards against content-based secret leaks and indirect script execution",
   "keywords": [
     "pi-package",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-mono-all",
-  "version": "1.2.3",
+  "version": "1.2.5",
   "description": "All pi-mono extensions and bundled skills",
   "type": "module",
   "keywords": [
@@ -9,24 +9,24 @@
     "pi-skill"
   ],
   "dependencies": {
-    "pi-mono-ask-user-question": "1.7.4",
     "pi-mono-auto-fix": "0.3.1",
+    "pi-mono-ask-user-question": "1.7.4",
     "pi-mono-btw": "1.7.4",
-    "pi-mono-context": "0.1.1",
     "pi-mono-clear": "1.7.3",
-    "pi-mono-figma": "0.2.2",
+    "pi-mono-context": "0.1.1",
     "pi-mono-context-guard": "1.7.3",
-    "pi-mono-linear": "0.2.3",
+    "pi-mono-figma": "0.2.2",
+    "pi-common": "0.1.1",
+    "pi-mono-linear": "0.2.4",
     "pi-mono-loop": "1.7.3",
-    "pi-mono-sentinel": "1.11.0",
-    "pi-mono-review": "1.8.2",
     "pi-mono-simplify": "1.7.3",
+    "pi-mono-status-line": "1.7.3",
+    "pi-mono-sentinel": "1.12.0",
+    "pi-mono-review": "1.8.2",
     "pi-mono-team-mode": "2.3.2",
-    "pi-mono-multi-edit": "1.7.3",
-    "pi-common": "0.1.1",
+    "pi-mono-usage": "0.1.1",
     "pi-mono-web-search": "0.1.0",
-    "pi-mono-status-line": "1.7.3",
-    "pi-mono-usage": "0.1.1"
+    "pi-mono-multi-edit": "1.7.3"
   },
   "bundledDependencies": [
     "pi-mono-ask-user-question",