pi-onedev-toolkit 0.2.2 → 0.4.0

package/CHANGELOG.md

@@ -1,6 +1,27 @@
 # Changelog
 
-## Unreleased
+## 0.4.0 — 2026-09-05
+
+### Changed
+
+- `issue`, `pull`, and `build` `list` actions with an explicit `project` now work even when the current repository has no OneDev remote: the query runs against a temporary scratch remote that is created and removed for the call.
+- Refreshed development dependencies (pi packages 0.85.1, typebox 1.3.27).
+
+
+## 0.3.0 — 2026-09-05
+
+### Changed
+
+- `issue`, `pull`, and `build` `list` actions now return a one-line-per-item digest instead of raw JSON (raw list items embed full Markdown descriptions); pass `full: true` for the raw payload. Digests fetch internally up to 512 KB; larger or non-JSON payloads fall back to the normal bounded raw output.
+- Query parameter descriptions now include common OneDev query examples (`open`, `submitted by "user"`, `Assignees is "user"`, `order by`), so most queries no longer need the 8–11 KB grammar dump from `query_description`.
+- `onedev_context` gains `list_projects` to discover accessible projects without activating a domain tool; it works from any repository once TOD is configured.
+
+### Fixed
+
+- One-shot watch notifications can no longer be lost when the emission consumer throws.
+- Watch polls record `lastError` (visible in `onedev_watch list`) instead of failing silently, and clear it on recovery.
+- Pull-attention watches read state only from top-level fields, so a nested build status can no longer masquerade as the PR state and cause spurious or missed wakes.
+- Watch snapshot calls are bounded to 10 seconds so one slow TOD call cannot stall other watches.
 
 ## 0.2.2 — 2026-09-04
 

package/README.md

@@ -28,7 +28,7 @@ When the current directory is a OneDev repository, the status line shows the act
 
 | Tool | Domains | Covers |
 | --- | --- | --- |
-| `onedev_context` (always active) | — | Readiness, authenticated health, login, and setup guidance |
+| `onedev_context` (always active) | — | Readiness, authenticated health, login, setup guidance, and accessible project discovery |
 | `onedev_tools` (always active) | — | Activate only the issue, pull, build, and watch domains needed now |
 | `onedev_issue` | issue | Query/get/comment issues, change fields/labels/state, log work, issue branches |
 | `onedev_pull` | pull | PR metadata/comments/code comments/labels/builds/patch, create/edit, reply/resolve review comments, approve, request changes, merge/discard |
@@ -37,7 +37,7 @@ When the current directory is a OneDev repository, the status line shows the act
 
 Lazy by design: domain tools activate only through `onedev_tools`, keeping the default tool list and system prompt light. Activation performs the first authenticated check and returns the server, project, and login context in the same response.
 
-Model-visible issue, PR, and build output defaults to 16 KB. PR patches, build logs, and build-spec schemas default to 32 KB. Use `max_bytes` to raise or lower a call's budget up to 128 KB; truncation keeps the payload head/tail and is reported explicitly. Internal watch polling remains separately bounded and is never copied into the model context.
+Model-visible issue, PR, and build output defaults to 16 KB. PR patches, build logs, and build-spec schemas default to 32 KB. Use `max_bytes` to raise or lower a call's budget up to 128 KB; truncation keeps the payload head/tail and is reported explicitly. List actions instead return one-line-per-item digests by default (pass `full` for the raw payload), so bulk queries stay small without losing items; payloads beyond the 512 KB internal fetch fall back to the normal bounded raw output. Internal watch polling remains separately bounded and is never copied into the model context.
 
 Remote and local mutations use Pi's real interactive approval UI. An approval can apply once, for the session, or persist for the exact server/project/operation in `~/.pi/agent/onedev-toolkit.json`; remove that file to revoke all saved approvals. Non-interactive sessions reject unapproved mutations. `build run` in local mode uses an isolated temporary Git index so TOD cannot leave the user's index staged; `check_spec` is treated as a mutation because TOD may upgrade `.onedev-buildspec.yml`.
 
@@ -55,6 +55,7 @@ Attachment download is intentionally not exposed: current TOD releases may send
 
 - Update TOD regularly from its upstream install script. `get_unit_test_report` reports an actionable upgrade error when the installed TOD predates that command.
 - Plain references require the current repository to have a OneDev remote from which TOD can infer the project. The toolkit reports `no_project` rather than pretending a qualified reference can bypass TOD's resolver.
+- `issue`, `pull`, and `build` `list` calls with an explicit `project` work from any repository: the toolkit binds TOD to a throwaway Git remote for the query and removes it afterwards.
 - Tool calls use `snake_case`, for example `for_code_review`, `target_branch`, `report_name`, and `interval_seconds`.
 
 ## Skills

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "pi-onedev-toolkit",
-	"version": "0.2.2",
+	"version": "0.4.0",
 	"description": "Lightweight OneDev integration for Pi via TOD: repo-aware issue, pull request, build, and watch tools",
 	"type": "module",
 	"author": {
@@ -53,12 +53,12 @@
 		"typebox": "*"
 	},
 	"devDependencies": {
-		"@earendil-works/pi-ai": "0.85.0",
-		"@earendil-works/pi-server": "0.85.0",
-		"@earendil-works/pi-coding-agent": "0.85.0",
+		"@earendil-works/pi-ai": "0.85.1",
+		"@earendil-works/pi-coding-agent": "0.85.1",
+		"@earendil-works/pi-server": "0.85.1",
 		"@types/node": "^22.19.0",
 		"@types/proper-lockfile": "4.1.4",
-		"typebox": "1.3.25",
+		"typebox": "1.3.27",
 		"typescript": "^7.0.2",
 		"vitest": "^4.1.10"
 	},

package/src/source-watch.ts

@@ -19,6 +19,7 @@ export interface OneDevWatchInfo {
 	intervalSeconds: number;
 	expiresAt: string;
 	failures: number;
+	lastError?: string;
 }
 
 export interface AddOneDevWatchOptions {
@@ -62,6 +63,7 @@ interface WatchRecord {
 	expiresAt: number;
 	nextPollAt: number;
 	failures: number;
+	lastError?: string;
 	baseline: WatchSnapshot;
 }
 
@@ -77,6 +79,8 @@ const MAX_INTERVAL_SECONDS = 300;
 const MAX_TTL_MINUTES = 24 * 60;
 const MAX_WATCHES = 10;
 const MAX_BACKOFF_MS = 5 * 60_000;
+
+const SNAPSHOT_TIMEOUT_MS = 10_000;
 const TERMINAL_BUILD_STATUSES = new Set([
 	"SUCCESSFUL",
 	"FAILED",
@@ -163,6 +167,33 @@ function firstBoolean(value: JsonValue, keys: readonly string[]): boolean | unde
 	return found;
 }
 
+function topLevelString(
+	value: JsonValue,
+	keys: readonly string[],
+): string | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		return undefined;
+	for (const key of keys) {
+		const child = value[key];
+		if (typeof child === "string" && child.trim() !== "") return child.trim();
+		if (typeof child === "number") return String(child);
+	}
+	return undefined;
+}
+
+function topLevelBoolean(
+	value: JsonValue,
+	keys: readonly string[],
+): boolean | undefined {
+	if (typeof value !== "object" || value === null || Array.isArray(value))
+		return undefined;
+	for (const key of keys) {
+		const child = value[key];
+		if (typeof child === "boolean") return child;
+	}
+	return undefined;
+}
+
 function unresolvedCodeComments(
 	value: JsonValue,
 ): Array<{ id: string | number; replies: number }> {
@@ -335,6 +366,7 @@ export class OneDevSourceWatchManager {
 			intervalSeconds: record.intervalMs / 1_000,
 			expiresAt: new Date(record.expiresAt).toISOString(),
 			failures: record.failures,
+			lastError: record.lastError,
 		};
 	}
 
@@ -353,6 +385,7 @@ export class OneDevSourceWatchManager {
 			const output = await runTod(this.deps.exec, ["build", "get", ref], {
 				cwd: context.cwd,
 				signal,
+				timeoutMs: SNAPSHOT_TIMEOUT_MS,
 				maxOutputBytes: 512_000,
 			});
 			const value = json(output.text, `build ${ref}`);
@@ -368,16 +401,19 @@ export class OneDevSourceWatchManager {
 			runTod(this.deps.exec, ["pr", "get", ref], {
 				cwd: context.cwd,
 				signal,
+				timeoutMs: SNAPSHOT_TIMEOUT_MS,
 				maxOutputBytes: 512_000,
 			}),
 			runTod(this.deps.exec, ["pr", "get-code-comments", ref], {
 				cwd: context.cwd,
 				signal,
+				timeoutMs: SNAPSHOT_TIMEOUT_MS,
 				maxOutputBytes: 512_000,
 			}),
 			runTod(this.deps.exec, ["pr", "get-builds", ref], {
 				cwd: context.cwd,
 				signal,
+				timeoutMs: SNAPSHOT_TIMEOUT_MS,
 				maxOutputBytes: 512_000,
 			}),
 		]);
@@ -397,17 +433,16 @@ export class OneDevSourceWatchManager {
 			"requestedChanges",
 		]);
 		const selected = {
-			state: firstString(pullValue, ["status", "state"]) ?? null,
+			state: topLevelString(pullValue, ["status", "state"]) ?? null,
 			head:
-				firstString(pullValue, [
-				"headCommitHash",
-				"sourceCommitHash",
-				"headCommit",
-				"sourceCommit",
+				topLevelString(pullValue, [
+					"headCommitHash",
+					"sourceCommitHash",
+					"headCommit",
+					"sourceCommit",
 				]) ?? null,
-			mergeable: firstBoolean(pullValue, ["mergeable"]) ?? null,
-			conflicted:
-				firstBoolean(pullValue, ["hasConflicts", "conflicted"]) ?? null,
+			mergeable: topLevelBoolean(pullValue, ["mergeable"]) ?? null,
+			conflicted: topLevelBoolean(pullValue, ["hasConflicts", "conflicted"]) ?? null,
 			unresolved,
 			reviews,
 			buildSignal,
@@ -496,21 +531,28 @@ export class OneDevSourceWatchManager {
 					if (generation !== this.#generation || !this.#records.has(record.id)) break;
 					if (this.#changed(record, snapshot)) {
 						this.#records.delete(record.id);
-						this.emit(this.#emission(record, snapshot));
+						try {
+							this.emit(this.#emission(record, snapshot));
+						} catch {
+							// a throwing consumer must not re-enter the poll-failure path
+						}
 						continue;
 					}
 					record.failures = 0;
+					record.lastError = undefined;
 					record.baseline = snapshot;
 					record.nextPollAt = this.now() + record.intervalMs;
-				} catch {
-					record.failures += 1;
-					record.nextPollAt =
-						this.now() +
-						Math.min(
-							record.intervalMs * 2 ** Math.min(record.failures, 6),
-							MAX_BACKOFF_MS,
-						);
-				}
+			} catch (error) {
+				record.failures += 1;
+				record.lastError =
+					error instanceof Error ? error.message : String(error);
+				record.nextPollAt =
+					this.now() +
+					Math.min(
+						record.intervalMs * 2 ** Math.min(record.failures, 6),
+						MAX_BACKOFF_MS,
+					);
+			}
 				if (record.expiresAt <= now) this.#records.delete(record.id);
 			}
 		} finally {

package/src/tools/build.ts

@@ -7,6 +7,7 @@ import { Type, type Static } from "typebox";
 import {
 	confirmMutation,
 	DEFAULT_LARGE_MODEL_OUTPUT_BYTES,
+	digestBuilds,
 	modelOutputBytes,
 	modelOutputLimit,
 	pushRepeated,
@@ -14,6 +15,7 @@ import {
 	REF_DESCRIPTION,
 	requireParam,
 	runInContext,
+	runListInContext,
 	toolResult,
 	withFooter,
 	type ToolDeps,
@@ -62,9 +64,24 @@ export interface BuildParams {
 	query?: string;
 	count?: number;
 	offset?: number;
+	full?: boolean;
 	max_bytes?: number;
 }
 
+/**
+ * Local unless another mode or an explicit branch/tag is given. Names the
+ * non-obvious defaulting rule shared by the arg builder and the isolated
+ * index path; both call sites must resolve it identically.
+ */
+function isLocalRunMode(
+	params: Pick<BuildParams, "mode" | "branch" | "tag">,
+): boolean {
+	return (
+		params.mode === "local" ||
+		(params.mode === undefined && !params.branch && !params.tag)
+	);
+}
+
 export function buildBuildArgs(params: BuildParams): string[] {
 	const args: string[] = ["build"];
 	const action = requireParam(params.action, "build", "action");
@@ -116,10 +133,7 @@ export function buildBuildArgs(params: BuildParams): string[] {
 			if (params.mode === "tag" && params.branch !== undefined) {
 				throw new Error("tag run mode does not accept branch");
 			}
-			if (
-				params.mode === "local" ||
-				(params.mode === undefined && !params.branch && !params.tag)
-			) {
+			if (isLocalRunMode(params)) {
 				args.push("--local");
 			} else if (params.mode === "branch" || params.branch !== undefined) {
 				args.push("--branch", requireParam(params.branch, action, "branch"));
@@ -225,6 +239,9 @@ export function registerBuildTool(pi: ExtensionAPI, deps: ToolDeps): void {
 		query: Type.Optional(Type.String({ description: QUERY_DESCRIPTION })),
 		count: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
 		offset: Type.Optional(Type.Integer({ minimum: 0 })),
+		full: Type.Optional(
+			Type.Boolean({ description: "Raw JSON instead of digest" }),
+		),
 		max_bytes: modelOutputBytes(),
 	}, { additionalProperties: false });
 	type Params = Static<typeof parameters>;
@@ -253,12 +270,17 @@ export function registerBuildTool(pi: ExtensionAPI, deps: ToolDeps): void {
 				});
 			}
 			// ponytail: build run streams the full log; preserve bounded metadata and the failure tail
-			const isLocalRun =
-				isRun &&
-				(params.mode === "local" ||
-					(params.mode === undefined && !params.branch && !params.tag));
+			const isLocalRun = isRun && isLocalRunMode(params);
 			let output: TodOutput;
-			if (isLocalRun) {
+			if (params.action === "list") {
+				output = await runListInContext(deps, args, {
+					signal,
+					project: params.project,
+					full: params.full,
+					maxOutputBytes: params.max_bytes,
+					digest: digestBuilds,
+				});
+			} else if (isLocalRun) {
 				output = await runLocalBuildWithIsolatedIndex(
 					deps,
 					args,

package/src/tools/common.ts

@@ -1,3 +1,6 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import type {
@@ -11,6 +14,7 @@ import type {
 import {
 	TodError,
 	runTod,
+	truncateMiddle,
 	type CommandExecutor,
 	type TodOutput,
 } from "../tod.js";
@@ -34,7 +38,7 @@ export const REF_DESCRIPTION =
 export const FIELDS_DESCRIPTION =
 	'"key=value" assignments; use valid_fields to discover values.';
 export const QUERY_DESCRIPTION =
-	"OneDev query; use query_description for syntax.";
+	'OneDev query; e.g. \'open\', \'submitted by "user"\', \'Assignees is "user"\', \'order by "Submit Date" desc\'; full syntax: query_description.';
 
 export function modelOutputBytes() {
 	return Type.Optional(
@@ -110,6 +114,308 @@ export function pushRepeated(
 	for (const value of values ?? []) args.push(flag, value);
 }
 
+/**
+ * One-line-per-item digests for list results. Raw OneDev list payloads embed
+ * full Markdown descriptions (~2 KB per item); digests keep bulk queries in a
+ * few KB so pagination stays lossless. Digests return undefined when the
+ * payload is not a JSON object array so callers fall back to the raw text.
+ */
+export const DIGEST_FETCH_BYTES = 512_000;
+
+type DigestItem = Record<string, unknown>;
+
+function parseDigestItems(text: string): DigestItem[] | undefined {
+	let parsed: unknown;
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+	if (!Array.isArray(parsed)) return undefined;
+	return parsed.every(
+		(item) => typeof item === "object" && item !== null && !Array.isArray(item),
+	)
+		? (parsed as DigestItem[])
+		: undefined;
+}
+
+function stringAt(
+	item: DigestItem,
+	keys: readonly string[],
+): string | undefined {
+	for (const key of keys) {
+		const value = item[key];
+		if (typeof value === "number") return String(value);
+		if (typeof value === "string" && value.trim() !== "") return value.trim();
+	}
+	return undefined;
+}
+
+function listAt(item: DigestItem, keys: readonly string[]): string[] {
+	for (const key of keys) {
+		const value = item[key];
+		if (Array.isArray(value) && value.length > 0) return value.map(String);
+	}
+	return [];
+}
+
+function clip(value: string, maxChars: number): string {
+	if (value.length <= maxChars) return value;
+	let end = maxChars - 1;
+	const previous = value.charCodeAt(end - 1);
+	if (previous >= 0xd800 && previous <= 0xdbff) end -= 1;
+	return `${value.slice(0, Math.max(end, 0))}…`;
+}
+
+function day(value: string | undefined): string | undefined {
+	return value === undefined ? undefined : value.slice(0, 10);
+}
+
+function digestLine(
+	ref: string,
+	tags: ReadonlyArray<string | undefined>,
+	summary: string,
+	trailer: ReadonlyArray<string | undefined>,
+): string {
+	const one = (value: string): string => value.replace(/\s+/g, " ");
+	const bracketed = tags
+		.filter((tag): tag is string => tag !== undefined)
+		.map(one);
+	const filled = trailer
+		.filter((part): part is string => part !== undefined)
+		.map(one);
+	const label = one(ref);
+	const head =
+		bracketed.length > 0 ? `${label} [${bracketed.join(" ")}]` : label;
+	const text = one(summary);
+	return `${head}${text !== "" ? ` ${text}` : ""}${filled.length > 0 ? ` · ${filled.join(" · ")}` : ""}`;
+}
+
+export function digestIssues(text: string): string | undefined {
+	const items = parseDigestItems(text);
+	if (!items) return undefined;
+	if (items.length === 0) return "(no issues)";
+	return items
+		.map((item) => {
+			const assignees = listAt(item, ["Assignees"]);
+			return digestLine(
+				stringAt(item, ["reference", "number"]) ?? "#?",
+				[
+					stringAt(item, ["state", "status"]),
+					...listAt(item, ["Priority"]),
+					...listAt(item, ["Type"]),
+				],
+				clip(stringAt(item, ["title"]) ?? "(untitled)", 120),
+				[
+					stringAt(item, ["submitter"]),
+					day(stringAt(item, ["submitDate"])),
+					assignees.length > 0
+						? `assigned: ${assignees.join(", ")}`
+						: undefined,
+				],
+			);
+		})
+		.join("\n");
+}
+
+export function digestPulls(text: string): string | undefined {
+	const items = parseDigestItems(text);
+	if (!items) return undefined;
+	if (items.length === 0) return "(no pull requests)";
+	return items
+		.map((item) => {
+			const flow = [
+				stringAt(item, ["sourceBranch"]),
+				stringAt(item, ["targetBranch"]),
+			]
+				.filter((branch): branch is string => branch !== undefined)
+				.join("→");
+			return digestLine(
+				stringAt(item, ["reference", "number"]) ?? "#?",
+				[stringAt(item, ["status", "state"])],
+				clip(stringAt(item, ["title"]) ?? "(untitled)", 120),
+				[
+					flow !== "" ? flow : undefined,
+					stringAt(item, ["submitter"]),
+					day(stringAt(item, ["submitDate"])),
+				],
+			);
+		})
+		.join("\n");
+}
+
+export function digestBuilds(text: string): string | undefined {
+	const items = parseDigestItems(text);
+	if (!items) return undefined;
+	if (items.length === 0) return "(no builds)";
+	return items
+		.map((item) =>
+			digestLine(
+				stringAt(item, ["reference", "number"]) ?? "#?",
+				[stringAt(item, ["status"])],
+				clip(stringAt(item, ["jobName"]) ?? "(unknown job)", 80),
+				[
+					stringAt(item, ["refName"])?.replace("refs/heads/", ""),
+					stringAt(item, ["agent", "submitter"]),
+					day(stringAt(item, ["submitDate"])),
+				],
+			),
+		)
+		.join("\n");
+}
+
+export function digestProjects(text: string): string | undefined {
+	const items = parseDigestItems(text);
+	if (!items) return undefined;
+	if (items.length === 0) return "(no projects)";
+	return items
+		.map((item) => {
+			const features = [
+				item.codeManagement === true ? "code" : undefined,
+				item.issueManagement === true ? "issues" : undefined,
+			].filter((feature): feature is string => feature !== undefined);
+			return digestLine(
+				stringAt(item, ["path"]) ?? "#?",
+				[],
+				clip(
+					stringAt(item, ["description"]) ?? stringAt(item, ["name"]) ?? "",
+					80,
+				),
+				[features.length > 0 ? `[${features.join("+")}]` : undefined],
+			);
+		})
+		.join("\n");
+}
+
+/**
+ * Run tod inside a throwaway Git repository whose only remote points at the
+ * requested OneDev project. TOD refuses `--project` queries when the working
+ * directory has no OneDev remote; the scratch repository supplies one
+ * without touching the user's checkout.
+ */
+async function runTodWithScratchRemote(
+	exec: CommandExecutor,
+	args: readonly string[],
+	serverUrl: string,
+	project: string,
+	options: { signal?: AbortSignal; maxOutputBytes: number },
+): Promise<TodOutput> {
+	const directory = await mkdtemp(join(tmpdir(), "pi-onedev-scratch-"));
+	try {
+		for (const gitArgs of [
+			["init", "--quiet", directory],
+			[
+				"remote",
+				"add",
+				"origin",
+				`${serverUrl.replace(/\/$/, "")}/${project}.git`,
+			],
+		]) {
+			const done = await exec("git", gitArgs, { cwd: directory });
+			if (done.code !== 0 || done.killed) {
+				throw new TodError(
+					`could not prepare a temporary OneDev project context: ${(done.stderr || done.stdout).trim() || `git ${gitArgs[0] ?? ""} failed`}`,
+				);
+			}
+		}
+		return await runTod(exec, [...args, "--working-dir", directory], {
+			signal: options.signal,
+			maxOutputBytes: options.maxOutputBytes,
+		});
+	} finally {
+		await rm(directory, { recursive: true, force: true });
+	}
+}
+
+async function finishListOutput(
+	fetch: (maxOutputBytes: number) => Promise<TodOutput>,
+	options: {
+		full?: boolean;
+		maxOutputBytes?: number;
+		digest: (text: string) => string | undefined;
+	},
+): Promise<TodOutput> {
+	if (options.full === true) {
+		return fetch(modelOutputLimit(options.maxOutputBytes));
+	}
+	const output = await fetch(DIGEST_FETCH_BYTES);
+	const limit = modelOutputLimit(options.maxOutputBytes);
+	const digested = options.digest(output.text);
+	if (
+		digested !== undefined &&
+		Buffer.byteLength(digested, "utf8") <= limit
+	) {
+		return {
+			text: digested,
+			truncated: false,
+			originalBytes: output.originalBytes,
+		};
+	}
+	// no digest, or one that outgrew the budget: the final model-visible
+	// text is still bounded by the normal output limit
+	const bounded = truncateMiddle(digested ?? output.text, limit);
+	return {
+		text: bounded.text,
+		truncated: bounded.truncated || output.truncated,
+		originalBytes: output.originalBytes,
+	};
+}
+
+/**
+ * Fetch a whole bounded list payload, then reduce it to a digest unless the
+ * caller opted into raw output. The internal fetch budget exceeds the
+ * model-visible cap on purpose: the digest, not the payload, reaches the
+ * model. Without an inferred project, an explicit `project` list query runs
+ * against a temporary scratch remote instead of failing.
+ */
+export async function runListInContext(
+	deps: ToolDeps,
+	args: readonly string[],
+	options: {
+		signal?: AbortSignal;
+		full?: boolean;
+		maxOutputBytes?: number;
+		project?: string;
+		digest: (text: string) => string | undefined;
+	},
+): Promise<TodOutput> {
+	const context = deps.context();
+	if (context.status !== "ready" || !context.project) {
+		const scratchServer = context.serverUrl;
+		const scratchProject = options.project;
+		if (
+			context.status !== "no_project" ||
+			scratchServer === undefined ||
+			scratchProject === undefined
+		) {
+			throw new TodError(
+				context.problem ??
+					"OneDev tools require a repository whose project can be inferred from a OneDev remote",
+			);
+		}
+		return finishListOutput(
+			(maxOutputBytes) =>
+				runTodWithScratchRemote(
+					deps.exec,
+					args,
+					scratchServer,
+					scratchProject,
+					{ signal: options.signal, maxOutputBytes },
+				),
+			options,
+		);
+	}
+	return finishListOutput(
+		(maxOutputBytes) =>
+			runTod(deps.exec, args, {
+				cwd: context.cwd,
+				signal: options.signal,
+				maxOutputBytes,
+			}),
+		options,
+	);
+}
+
 export function confirmMutation(
 	deps: ToolDeps,
 	ctx: ExtensionContext,

package/src/tools/index.ts

@@ -2,8 +2,15 @@ import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { StringEnum } from "@earendil-works/pi-ai";
 import { Type } from "typebox";
 import { formatContext, setupGuidance } from "../context.js";
+import { runTod } from "../tod.js";
 import type { OneDevSourceWatchManager } from "../source-watch.js";
-import { toolResult, type ToolDeps } from "./common.js";
+import {
+	DIGEST_FETCH_BYTES,
+	digestProjects,
+	toolResult,
+	withFooter,
+	type ToolDeps,
+} from "./common.js";
 import { registerBuildTool } from "./build.js";
 import { registerIssueTool } from "./issue.js";
 import { registerPullTool } from "./pull.js";
@@ -46,7 +53,17 @@ function registerContextTool(pi: ExtensionAPI, deps: ToolDeps): void {
 		description: "Inspect OneDev readiness, health, login, or setup.",
 		parameters: Type.Object(
 			{
-				action: StringEnum(["current", "health", "login_name", "setup"]),
+				action: StringEnum([
+					"current",
+					"health",
+					"login_name",
+					"setup",
+					"list_projects",
+				]),
+				count: Type.Optional(
+					Type.Integer({ minimum: 1, maximum: 100, description: "Default: 25" }),
+				),
+				offset: Type.Optional(Type.Integer({ minimum: 0 })),
 			},
 			{ additionalProperties: false },
 		),
@@ -57,6 +74,31 @@ function registerContextTool(pi: ExtensionAPI, deps: ToolDeps): void {
 			if (params.action === "setup") {
 				return toolResult(setupGuidance(deps.context()));
 			}
+			if (params.action === "list_projects") {
+				const context = deps.context();
+				if (
+					context.status === "not_configured" ||
+					context.status === "unavailable"
+				) {
+					return toolResult(setupGuidance(context));
+				}
+				const args = ["project", "list", "--count", String(params.count ?? 25)];
+				if (params.offset !== undefined)
+					args.push("--offset", String(params.offset));
+				const output = await runTod(deps.exec, args, {
+					cwd: context.cwd,
+					signal,
+					maxOutputBytes: DIGEST_FETCH_BYTES,
+				});
+				const digested = digestProjects(output.text);
+				return toolResult(
+					withFooter(
+						digested ?? output.text,
+						context,
+						digested === undefined && output.truncated,
+					),
+				);
+			}
 			const context = await deps.refreshContext({
 				verifyAuth: true,
 				force: true,

package/src/tools/issue.ts

@@ -4,12 +4,14 @@ import { Type, type Static } from "typebox";
 import {
 	FIELDS_DESCRIPTION,
 	confirmMutation,
+	digestIssues,
 	modelOutputBytes,
 	pushRepeated,
 	QUERY_DESCRIPTION,
 	REF_DESCRIPTION,
 	requireParam,
 	runInContext,
+	runListInContext,
 	toolResult,
 	withFooter,
 	type ToolDeps,
@@ -66,6 +68,7 @@ export interface IssueParams {
 	query?: string;
 	count?: number;
 	offset?: number;
+	full?: boolean;
 	max_bytes?: number;
 }
 
@@ -200,6 +203,9 @@ export function registerIssueTool(pi: ExtensionAPI, deps: ToolDeps): void {
 			}),
 		),
 		offset: Type.Optional(Type.Integer({ minimum: 0 })),
+		full: Type.Optional(
+			Type.Boolean({ description: "Raw JSON instead of digest" }),
+		),
 		max_bytes: modelOutputBytes(),
 	}, { additionalProperties: false });
 	type Params = Static<typeof parameters>;
@@ -223,10 +229,19 @@ export function registerIssueTool(pi: ExtensionAPI, deps: ToolDeps): void {
 					signal,
 				});
 			}
-			const output = await runInContext(deps, args, {
-				signal,
-				maxOutputBytes: params.max_bytes,
-			});
+			const output =
+				params.action === "list"
+					? await runListInContext(deps, args, {
+							signal,
+							project: params.project,
+							full: params.full,
+							maxOutputBytes: params.max_bytes,
+							digest: digestIssues,
+						})
+					: await runInContext(deps, args, {
+							signal,
+							maxOutputBytes: params.max_bytes,
+						});
 			return toolResult(
 				withFooter(output.text, deps.context(), output.truncated),
 				{

package/src/tools/pull.ts

@@ -4,12 +4,14 @@ import { Type, type Static } from "typebox";
 import {
 	confirmMutation,
 	DEFAULT_LARGE_MODEL_OUTPUT_BYTES,
+	digestPulls,
 	modelOutputBytes,
 	pushRepeated,
 	QUERY_DESCRIPTION,
 	REF_DESCRIPTION,
 	requireParam,
 	runInContext,
+	runListInContext,
 	toolResult,
 	withFooter,
 	type ToolDeps,
@@ -88,6 +90,7 @@ export interface PullParams {
 	query?: string;
 	count?: number;
 	offset?: number;
+	full?: boolean;
 	max_bytes?: number;
 }
 
@@ -274,6 +277,9 @@ export function registerPullTool(pi: ExtensionAPI, deps: ToolDeps): void {
 		query: Type.Optional(Type.String({ description: QUERY_DESCRIPTION })),
 		count: Type.Optional(Type.Integer({ minimum: 1, maximum: 100 })),
 		offset: Type.Optional(Type.Integer({ minimum: 0 })),
+		full: Type.Optional(
+			Type.Boolean({ description: "Raw JSON instead of digest" }),
+		),
 		max_bytes: modelOutputBytes(),
 	}, { additionalProperties: false });
 	type Params = Static<typeof parameters>;
@@ -298,14 +304,23 @@ export function registerPullTool(pi: ExtensionAPI, deps: ToolDeps): void {
 					signal,
 				});
 			}
-			const output = await runInContext(deps, args, {
-				signal,
-				maxOutputBytes:
-					params.max_bytes ??
-					(params.action === "get_patch"
-						? DEFAULT_LARGE_MODEL_OUTPUT_BYTES
-						: undefined),
-			});
+			const output =
+				params.action === "list"
+					? await runListInContext(deps, args, {
+							signal,
+							project: params.project,
+							full: params.full,
+							maxOutputBytes: params.max_bytes,
+							digest: digestPulls,
+						})
+					: await runInContext(deps, args, {
+							signal,
+							maxOutputBytes:
+								params.max_bytes ??
+								(params.action === "get_patch"
+									? DEFAULT_LARGE_MODEL_OUTPUT_BYTES
+									: undefined),
+						});
 			return toolResult(
 				withFooter(output.text, deps.context(), output.truncated),
 				{