pi-onedev-toolkit 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 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
+
+### Changed
+
+- Compressed model-visible tool schemas and bundled workflow prompts without changing tool names, actions, validations, or approval gates; tests now enforce schema and skill byte budgets.
+- Model-visible output now defaults to 16 KB for normal results and 32 KB for PR patches, build logs, and build-spec schemas. `max_bytes` can request up to 128 KB; internal watch polling remains independent.
+
 ## 0.2.1 — 2026-09-03
 
 ### Fixed

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,6 +37,8 @@ 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. 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`.
 
 Watches are session-scoped and one-shot. They use one timer, bounded polling, expiration and backoff, and wake the agent with metadata only. The agent retrieves logs, comments, or build details with the corresponding read tool. At most ten watches may be active; session changes and shutdown clear them.
@@ -60,6 +62,12 @@ Attachment download is intentionally not exposed: current TOD releases may send
 - `onedev-issue-to-pr` — gather issue context, branch, implement, present for review, then push and open the PR
 - `onedev-pr-review` — full-context PR review with line-anchored findings; submits only on explicit request
 
+If you use only tools and slash commands, omit both workflow entries from every prompt while keeping the extension and tools:
+
+```json
+{ "source": "npm:pi-onedev-toolkit", "skills": [] }
+```
+
 ## Development
 
 ```bash

package/package.json

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

package/skills/onedev-issue-to-pr/SKILL.md

@@ -1,60 +1,26 @@
 ---
 name: onedev-issue-to-pr
-description: Implement a OneDev issue end to end - gather issue context, branch, implement, then (after user approval) push and open a linked pull request. Use when the user asks to work on, implement, or fix a OneDev issue.
+description: "Implement a OneDev issue and open a linked PR only after user approval."
 ---
 
-# OneDev issue to pull request
+# OneDev Issue to Pull Request
 
-## Prerequisites
+## Rules
 
-- Call `onedev_tools` with domains `["issue", "pull"]` first; note your login name from the returned context. If activation reports a readiness problem, use `onedev_context` `setup` and stop until it is resolved.
-- The current repository belongs to the issue's project (plain refs like `123` resolve against it).
+- Activate `issue` and `pull` together with `onedev_tools`; note the returned login. On readiness failure, use `onedev_context setup` and stop.
+- Plain refs use the current repository's OneDev project. Never guess a missing ref or project.
+- Preserve unrelated local changes. If checkout is dirty, report and stop; never stash automatically.
+- Do not push, comment, or open a PR before the workflow checkpoint and explicit user approval. Toolkit mutations still require Pi UI approval.
 
 ## Workflow
 
-1. **Resolve the issue reference.** Use the reference from the prompt, or derive it
-   with `onedev_issue` action `current_reference`. If neither works, stop and report.
+1. Resolve the prompt ref or use `onedev_issue current_reference`; stop if neither works.
+2. Prepare the branch with `onedev_issue checkout` using `for_write: true`.
+3. Read `onedev_issue get` and `get_comments`; use author/login context and derive acceptance criteria from the full discussion.
+4. When failure evidence matters, activate `build`; inspect build metadata and start `get_log` with `max_bytes=32000`, raising it only if truncation hides required evidence. Follow same-commit dependency failures as the likely root cause; different-commit failures are inherited.
+5. Implement the smallest complete change and run the narrowest relevant test. Optionally run local OneDev CI with `onedev_build run mode=local`.
+6. **Stop for review.** Show the change, checks, and any issue comment you intend to post. Do not submit anything.
+7. After explicit approval, read `onedev_pull commit_message_requirement` and `title_description_requirement`; empty output means no extra requirement. Commit and push with local Git, then create the PR against the intended target branch. Link the issue in the description when the issue branch does not imply it. Post only the approved issue comment.
+8. For long CI, activate `watch` and start `onedev_watch watch_build`; re-read the build after the metadata-only notification.
 
-2. **Prepare the checkout** (unless the user says otherwise):
-   `onedev_issue` action `checkout` with `ref` and `for_write: true`.
-   It creates the server-side issue branch and sets up tracking.
-   If the working copy is dirty, report it and stop — do not stash on your own.
-
-3. **Read the full issue context** — never work from the prompt alone:
-   - `onedev_issue` `get` (title, description, fields, submitter)
-   - `onedev_issue` `get_comments`
-   - Match your login name against submitter/comment authors to understand your role.
-   - If a failed build is part of the issue, gather evidence with `onedev_build`
-     after activating the `build` domain (`get`, `get_log`, and a named
-     `get_unit_test_report` when useful) before planning changes. Follow `Dependency build … failed`
-     chains: same-commit dependency failures are the real target; different-commit
-     ones mean the failure is inherited.
-
-4. **Implement the work.** Code changes, or an explanatory issue comment if no code
-   is needed. Run the smallest relevant test. Optionally validate CI locally with
-   `onedev_build` `run` (`mode: "local"`) before committing.
-
-5. **STOP — present for review.** Summarize the change and the comment you intend
-   to post. Do not push or post anything yet. This is the mandatory checkpoint.
-
-6. **After explicit user approval, submit:**
-   - Compose the commit message against the server requirements:
-     `onedev_pull` `commit_message_requirement` (and `title_description_requirement`
-     before creating the PR). Empty output means no requirement.
-   - `git add -A && git commit && git push` on the issue branch.
-   - Create the PR: `onedev_pull` `create` with `title`, `description`, and
-     `target_branch` (source branch defaults to the current branch). The issue link
-     is inferred from the branch; state it in the description if not.
-   - Post the drafted comment with `onedev_issue` `add_comment` if one was prepared.
-
-7. **For long-running CI**, activate `watch` and use `onedev_watch` `watch_build`
-   after obtaining a build reference. The notification is one-shot and metadata-only;
-   inspect the build with `onedev_build` when it fires.
-
-## Notes
-
-- Write comment text in Markdown.
-- Reference entities as `#123` (current project), `project#123`, or `PROJ-123`.
-- If blocked mid-workflow, report the command and error, and stop.
-- Toolkit mutations still open Pi's interactive approval UI. Do not try to bypass
-  it with a confirmation parameter.
+Use Markdown for comments and `#123`, `project#123`, or `PROJ-123` for entities. On failure, report the command/error and stop; never invent a confirmation parameter.

package/skills/onedev-pr-review/SKILL.md

@@ -1,71 +1,28 @@
 ---
 name: onedev-pr-review
-description: Review a OneDev pull request - gather PR context, builds, and fixed issues, read the review-scoped patch, draft findings with line-anchored code comments, and submit the review or merge only on explicit request. Use when the user asks to review, address feedback on, or merge a OneDev pull request.
+description: "Review a OneDev PR; publish findings or merge only when asked."
 ---
 
-# OneDev pull request review
+# OneDev Pull Request Review
 
-## Prerequisites
+## Rules
 
-- Call `onedev_tools` with domains `["pull", "issue", "build"]`; note your login name. If activation reports a readiness problem, use `onedev_context` `setup` and stop until it is resolved.
-- The current repository belongs to the PR's source or target project.
+- Activate `pull`, `issue`, and `build` together with `onedev_tools`; note the returned login. On readiness failure, use `onedev_context setup` and stop.
+- Resolve the exact PR in its source/target repository. Never review from a patch alone.
+- Analysis is read-only. Draft first; publish findings, change review state, or merge only after explicit user request and Pi UI approval.
+- Never alter another user's code comments.
 
-## Gather context (never review from the patch alone)
+## Workflow
 
-1. **Resolve the PR reference** from the prompt or `onedev_pull` `current_reference`.
+1. Resolve the prompt ref or use `onedev_pull current_reference`.
+2. Checkout for inspection; use `for_write: true` only when changing code. Dirty checkout means report and stop.
+3. Read PR metadata, comments, code comments, and builds. Query fixed issues with `fixed in pull request "<ref>"`, then read their bodies/comments as the primary specification. Match authors against the returned login.
+4. Investigate every failed build. Start `onedev_build get_log` with `max_bytes=32000`; raise it only if truncation hides required evidence. Follow same-commit dependency failures before blaming the current job.
+5. Read `onedev_pull get_patch` with `for_code_review: true` and `max_bytes=32000`; inspect checkout files and callers when context is missing.
+6. Keep only concrete correctness, regression, security, data-loss, error-handling, or coverage findings. Triage prior discussion: reply where needed, resolve only addressed comments you own, and leave unrelated comments alone.
+7. Draft line findings with file/right-side lines, outside-patch findings as one overall comment, and `approve` or `request_changes` only when acting as a pending reviewer.
+8. **Stop and present** findings, replies, outcome, and merge plan. Submit nothing.
+9. On explicit request, publish the approved draft. For merge, satisfy `commit_message_requirement`; squash messages should reflect PR and fixed issues. Ask before rewriting commits for rebase-based conflict resolution.
+10. When waiting, activate `watch` and use `watch_pull_attention`; re-read PR state after its metadata-only notification.
 
-2. **Checkout** for inspection: `onedev_pull` `checkout` (`for_write: true` when you
-   will change code). Dirty working copy → report and stop.
-
-3. **Read everything:**
-   - `onedev_pull` `get` — title, description, source/target, merge strategy, status,
-     submitter, reviewers, review state.
-   - `onedev_pull` `get_comments` and `get_code_comments` — note code-comment `id`s,
-     file, line range, resolution state, replies.
-   - Fixed issues: `onedev_issue` `list` with query `fixed in pull request "<ref>"`,
-     then `get` / `get_comments` on each. Treat fixed issues as the primary spec
-     for what the PR should accomplish.
-   - `onedev_pull` `get_builds` — investigate every `FAILED` build with
-     `onedev_build` `get` / `get_log` before reviewing code.
-   - Match your login name against authors to understand your role
-     (pending reviewer, prior commenter, outsider).
-
-## Review
-
-1. Read the review-scoped patch: `onedev_pull` `get_patch` with
-   `for_code_review: true`. Read files in the checkout when the patch lacks context.
-   Check correctness, edge cases, security, style, and test coverage.
-
-2. **Triage prior discussion:** resolve addressed code comments, reply where new
-   information is needed, leave unrelated unresolved ones alone. Never modify
-   another user's code comments. Use `reply_code_comment`, `resolve_code_comment`,
-   or `unresolve_code_comment` with the comment `id`.
-
-3. **Draft findings:**
-   - Line-anchored findings → `onedev_pull` `add_code_comment` (`file`, `from_line`,
-     optional `to_line` — must be an added or context line visible in the patch).
-   - Outside-patch findings → one overall PR comment with file paths and lines.
-   - Review outcome if you are a pending reviewer: `approve` or `request_changes`
-     with a `summary`.
-
-4. **STOP — present the draft** (findings, replies, outcomes, merge plan).
-   Submit nothing yet.
-
-5. **On explicit request only:**
-   - Post findings/comments/review outcome.
-   - Merge: the toolkit asks for real interactive approval. For squash merges,
-     compose the commit message from PR title/description + fixed issues,
-     satisfying `commit_message_requirement` for the target project/branch.
-   - Resolving merge conflicts: fetch the target branch, merge with the PR's
-     strategy without committing, resolve, verify clean `git status`, commit.
-     For rebase-based strategies, ask for direction before rewriting commits.
-
-6. **When waiting on updates**, activate `watch` and use `onedev_watch`
-   `watch_pull_attention`. It wakes once for a head/state/review/comment/build
-   signal change and includes no comment bodies; re-read the PR after it fires.
-
-## Notes
-
-- Comment text is Markdown; entity refs are `#123`, `project#123`, or `PROJ-123`.
-- Toolkit mutations still open Pi's interactive approval UI. Do not add or invent
-  a confirmation parameter.
+Use Markdown and `#123`, `project#123`, or `PROJ-123` refs. Never invent a confirmation parameter.

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

@@ -6,11 +6,16 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { Type, type Static } from "typebox";
 import {
 	confirmMutation,
+	DEFAULT_LARGE_MODEL_OUTPUT_BYTES,
+	digestBuilds,
+	modelOutputBytes,
+	modelOutputLimit,
 	pushRepeated,
 	QUERY_DESCRIPTION,
 	REF_DESCRIPTION,
 	requireParam,
 	runInContext,
+	runListInContext,
 	toolResult,
 	withFooter,
 	type ToolDeps,
@@ -59,6 +64,22 @@ 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[] {
@@ -112,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"));
@@ -154,6 +172,7 @@ async function runLocalBuildWithIsolatedIndex(
 	deps: ToolDeps,
 	args: string[],
 	signal?: AbortSignal,
+	maxOutputBytes?: number,
 ): Promise<TodOutput> {
 	if (process.platform === "win32") {
 		throw new TodError(
@@ -183,7 +202,7 @@ async function runLocalBuildWithIsolatedIndex(
 			cwd: context.cwd,
 			signal,
 			timeoutMs: BUILD_RUN_TIMEOUT_MS,
-			maxOutputBytes: 24_000,
+			maxOutputBytes: modelOutputLimit(maxOutputBytes, 24_000),
 			environment: { GIT_INDEX_FILE: isolatedIndex },
 		});
 	} catch (error) {
@@ -201,51 +220,36 @@ async function runLocalBuildWithIsolatedIndex(
 
 export function registerBuildTool(pi: ExtensionAPI, deps: ToolDeps): void {
 	const parameters = Type.Object({
-		action: StringEnum(BUILD_ACTIONS, {
-			description:
-				"list, get, get_log, get_code_problems, get_unit_test_report, get_changes_since_success, run, check_spec (may upgrade .onedev-buildspec.yml), get_spec_schema, query_description",
-		}),
+		action: StringEnum(BUILD_ACTIONS),
 		ref: Type.Optional(Type.String({ description: REF_DESCRIPTION })),
-		report_name: Type.Optional(
-			Type.String({ description: "Report name quoted in the build log" }),
-		),
+		report_name: Type.Optional(Type.String()),
 		severity: Type.Optional(StringEnum(SEVERITY_LEVELS)),
-		job: Type.Optional(
-			Type.String({ description: "Job name defined in .onedev-buildspec.yml" }),
-		),
+		job: Type.Optional(Type.String()),
 		mode: Type.Optional(
-			StringEnum(RUN_MODES, {
-				description:
-					"run: local (uncommitted changes), branch, or tag; default local",
-			}),
-		),
-		branch: Type.Optional(
-			Type.String({ description: "run with mode=branch: branch to run against" }),
-		),
-		tag: Type.Optional(
-			Type.String({ description: "run with mode=tag: tag to run against" }),
+			StringEnum(RUN_MODES, { description: "Default: local" }),
 		),
+		branch: Type.Optional(Type.String()),
+		tag: Type.Optional(Type.String()),
 		params: Type.Optional(
-			Type.Array(Type.String(), {
-				description: 'Job parameters as "key=value", repeatable (-p)',
-			}),
+			Type.Array(Type.String(), { description: '"key=value" parameters' }),
 		),
 		project: Type.Optional(
-			Type.String({
-				description: "Project path for list; defaults to the current project",
-			}),
+			Type.String({ description: "Default: current project" }),
 		),
 		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>;
 
 	pi.registerTool({
 		name: "onedev_build",
 		label: "OneDev Builds",
-		description:
-			"Inspect OneDev CI/CD: query builds, read logs and code-problem reports, diff changes since the last success, validate the build spec, and run jobs (including against uncommitted local changes).",
+		description: "Read OneDev builds, logs, reports, and changes; validate or run jobs.",
 		parameters,
 		async execute(_toolCallId, params: Params, signal, _onUpdate, ctx) {
 			const isRun = params.action === "run";
@@ -266,18 +270,34 @@ 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) {
-				output = await runLocalBuildWithIsolatedIndex(deps, args, signal);
+			if (params.action === "list") {
+				output = await runListInContext(deps, args, {
+					signal,
+					full: params.full,
+					maxOutputBytes: params.max_bytes,
+					digest: digestBuilds,
+				});
+			} else if (isLocalRun) {
+				output = await runLocalBuildWithIsolatedIndex(
+					deps,
+					args,
+					signal,
+					params.max_bytes,
+				);
 			} else {
 				output = await runInContext(deps, args, {
 					signal,
 					timeoutMs: isRun ? BUILD_RUN_TIMEOUT_MS : undefined,
-					maxOutputBytes: isRun ? 24_000 : undefined,
+					maxOutputBytes:
+						params.max_bytes ??
+						(isRun
+							? 24_000
+							: params.action === "get_log" ||
+									params.action === "get_spec_schema"
+								? DEFAULT_LARGE_MODEL_OUTPUT_BYTES
+								: undefined),
 				});
 			}
 			return toolResult(

package/src/tools/common.ts

@@ -1,4 +1,5 @@
 import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
 import type {
 	ContextRefreshOptions,
 	OneDevSessionContext,
@@ -10,6 +11,7 @@ import type {
 import {
 	TodError,
 	runTod,
+	truncateMiddle,
 	type CommandExecutor,
 	type TodOutput,
 } from "../tod.js";
@@ -24,12 +26,32 @@ export interface ToolDeps {
 	approvals: MutationApprovalManager;
 }
 
+export const DEFAULT_MODEL_OUTPUT_BYTES = 16_000;
+export const DEFAULT_LARGE_MODEL_OUTPUT_BYTES = 32_000;
+export const MAX_MODEL_OUTPUT_BYTES = 128_000;
+
 export const REF_DESCRIPTION =
-	"OneDev reference: plain number (123), #number, project#number (myproject#123), or issue key (PROJ-123). Plain numbers resolve against the current repository's project.";
+	"Ref: 123, #123, project#123, or PROJ-123; plain numbers use the current project.";
 export const FIELDS_DESCRIPTION =
-	'Issue field assignments as "key=value" strings, repeatable. Discover valid fields and values with the valid_fields action.';
+	'"key=value" assignments; use valid_fields to discover values.';
 export const QUERY_DESCRIPTION =
-	"OneDev query, e.g. '\"State\" is \"Open\"' or 'assignee is me'. Syntax reference: query_description action.";
+	'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(
+		Type.Integer({ minimum: 1_000, maximum: MAX_MODEL_OUTPUT_BYTES }),
+	);
+}
+
+export function modelOutputLimit(
+	requested: number | undefined,
+	fallback = DEFAULT_MODEL_OUTPUT_BYTES,
+): number {
+	return Math.min(
+		MAX_MODEL_OUTPUT_BYTES,
+		Math.max(1_000, requested ?? fallback),
+	);
+}
 
 export function toolResult(
 	text: string,
@@ -65,7 +87,7 @@ export async function runInContext(
 		cwd: context.cwd,
 		signal: options.signal,
 		timeoutMs: options.timeoutMs,
-		maxOutputBytes: options.maxOutputBytes,
+		maxOutputBytes: modelOutputLimit(options.maxOutputBytes),
 	});
 }
 
@@ -89,6 +111,236 @@ 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");
+}
+
+/**
+ * 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.
+ */
+export async function runListInContext(
+	deps: ToolDeps,
+	args: readonly string[],
+	options: {
+		signal?: AbortSignal;
+		full?: boolean;
+		maxOutputBytes?: number;
+		digest: (text: string) => string | undefined;
+	},
+): Promise<TodOutput> {
+	const context = deps.context();
+	if (context.status !== "ready" || !context.project) {
+		throw new TodError(
+			context.problem ??
+				"OneDev tools require a repository whose project can be inferred from a OneDev remote",
+		);
+	}
+	if (options.full === true) {
+		return runTod(deps.exec, args, {
+			cwd: context.cwd,
+			signal: options.signal,
+			maxOutputBytes: modelOutputLimit(options.maxOutputBytes),
+		});
+	}
+	const output = await runTod(deps.exec, args, {
+		cwd: context.cwd,
+		signal: options.signal,
+		maxOutputBytes: 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,
+	};
+}
+
 export function confirmMutation(
 	deps: ToolDeps,
 	ctx: ExtensionContext,
@@ -111,7 +363,7 @@ export function withFooter(
 ): string {
 	const parts = [body || "(no output)"];
 	if (truncated)
-		parts.push("(output truncated; narrow the query or fetch a single entity)");
+		parts.push("(output truncated; narrow the query or raise max_bytes)");
 	parts.push(contextFooter(context));
 	return parts.filter(Boolean).join("\n\n");
 }

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";
@@ -43,11 +50,20 @@ function registerContextTool(pi: ExtensionAPI, deps: ToolDeps): void {
 	pi.registerTool({
 		name: "onedev_context",
 		label: "OneDev Context",
-		description:
-			"Inspect OneDev readiness without loading domain tools. Use health for an authenticated re-check and setup for actionable configuration guidance.",
+		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 },
 		),
@@ -58,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,
@@ -85,8 +126,7 @@ export function registerOnedevTools(
 	pi.registerTool({
 		name: "onedev_tools",
 		label: "OneDev Tools",
-		description:
-			"Activate only the OneDev domains needed for the current task. Returns authenticated server, project, and login context with the activation result.",
+		description: "Activate needed OneDev domains and return authenticated context.",
 		promptGuidelines: [
 			"Use onedev_tools before an unavailable OneDev domain operation.",
 		],
@@ -97,7 +137,6 @@ export function registerOnedevTools(
 					minItems: 1,
 					maxItems: 4,
 					uniqueItems: true,
-					description: "Activate issue, pull, build, and/or watch in one call",
 				}),
 			},
 			{ additionalProperties: false },

package/src/tools/issue.ts

@@ -4,11 +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,
@@ -65,6 +68,8 @@ export interface IssueParams {
 	query?: string;
 	count?: number;
 	offset?: number;
+	full?: boolean;
+	max_bytes?: number;
 }
 
 export function buildIssueArgs(params: IssueParams): string[] {
@@ -161,66 +166,54 @@ export function buildIssueArgs(params: IssueParams): string[] {
 
 export function registerIssueTool(pi: ExtensionAPI, deps: ToolDeps): void {
 	const parameters = Type.Object({
-		action: StringEnum(ISSUE_ACTIONS, {
-			description:
-				"list (query issues), get, get_comments, create, edit, change_state, add_comment, link, log_work, create_branch, checkout (branch locally), current_reference (issue for current branch), valid_fields, valid_links, query_description",
-		}),
+		action: StringEnum(ISSUE_ACTIONS),
 		ref: Type.Optional(Type.String({ description: REF_DESCRIPTION })),
 		title: Type.Optional(Type.String()),
-		description: Type.Optional(Type.String({ description: "Markdown body" })),
+		description: Type.Optional(Type.String()),
 		state: Type.Optional(
-			Type.String({
-				description:
-					"Target state, e.g. Open or Released; discover via valid_fields",
-			}),
-		),
-		comment: Type.Optional(
-			Type.String({ description: "Markdown note attached to the action" }),
+			Type.String({ description: "Use valid_fields to discover states" }),
 		),
-		content: Type.Optional(Type.String({ description: "Markdown comment text" })),
+		comment: Type.Optional(Type.String()),
+		content: Type.Optional(Type.String()),
 		link_name: Type.Optional(
-			Type.String({ description: "Issue link name; discover via valid_links" }),
-		),
-		target_ref: Type.Optional(
-			Type.String({ description: "Target issue reference for the link action" }),
-		),
-		hours: Type.Optional(
-			Type.Integer({ minimum: 1, description: "Hours to log for log_work" }),
+			Type.String({ description: "Use valid_links to discover names" }),
 		),
+		target_ref: Type.Optional(Type.String()),
+		hours: Type.Optional(Type.Integer({ minimum: 1 })),
 		fields: Type.Optional(
 			Type.Array(Type.String(), { description: FIELDS_DESCRIPTION }),
 		),
 		iterations: Type.Optional(Type.Array(Type.String())),
 		own_estimated_time: Type.Optional(
-			Type.Number({ minimum: 0, description: "Estimated hours" }),
+			Type.Number({ minimum: 0, description: "Hours" }),
 		),
 		confidential: Type.Optional(Type.Boolean()),
 		for_write: Type.Optional(
-			Type.Boolean({ description: "checkout: set up the branch for pushing" }),
+			Type.Boolean({ description: "Prepare checkout for push" }),
 		),
 		project: Type.Optional(
-			Type.String({
-				description:
-					"Project path for list/create; defaults to the current project",
-			}),
+			Type.String({ description: "Default: current project" }),
 		),
 		query: Type.Optional(Type.String({ description: QUERY_DESCRIPTION })),
 		count: Type.Optional(
 			Type.Integer({
 				minimum: 1,
 				maximum: 100,
-				description: "Page size for list (default 25, max 100)",
+				description: "Default: 25",
 			}),
 		),
 		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>;
 
 	pi.registerTool({
 		name: "onedev_issue",
 		label: "OneDev Issues",
-		description:
-			"Read and edit OneDev issues: query, inspect, comment, change fields/labels/state, log work, manage issue branches. Runs in the current repository's project; plain numbers resolve against it.",
+		description: "Read/manage OneDev issues, comments, fields, work, and branches.",
 		parameters,
 		async execute(_toolCallId, params: Params, signal, _onUpdate, ctx) {
 			const args = buildIssueArgs(params);
@@ -236,7 +229,18 @@ export function registerIssueTool(pi: ExtensionAPI, deps: ToolDeps): void {
 					signal,
 				});
 			}
-			const output = await runInContext(deps, args, { signal });
+			const output =
+				params.action === "list"
+					? await runListInContext(deps, args, {
+							signal,
+							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

@@ -3,11 +3,15 @@ import { StringEnum } from "@earendil-works/pi-ai";
 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,
@@ -86,6 +90,8 @@ export interface PullParams {
 	query?: string;
 	count?: number;
 	offset?: number;
+	full?: boolean;
+	max_bytes?: number;
 }
 
 export function buildPullArgs(params: PullParams): string[] {
@@ -232,92 +238,56 @@ export function buildPullArgs(params: PullParams): string[] {
 
 export function registerPullTool(pi: ExtensionAPI, deps: ToolDeps): void {
 	const parameters = Type.Object({
-		action: StringEnum(PULL_ACTIONS, {
-			description:
-				"list, get, get_comments, get_code_comments, get_builds, get_patch, create, edit, add_comment, add_code_comment, reply_code_comment, resolve_code_comment, unresolve_code_comment, approve, request_changes, merge, discard, checkout, current_reference, valid_labels, query_description, title_description_requirement, commit_message_requirement",
-		}),
+		action: StringEnum(PULL_ACTIONS),
 		ref: Type.Optional(Type.String({ description: REF_DESCRIPTION })),
 		title: Type.Optional(Type.String()),
-		description: Type.Optional(Type.String({ description: "Markdown body" })),
-		content: Type.Optional(Type.String({ description: "Markdown comment text" })),
-		summary: Type.Optional(
-			Type.String({
-				description: "Markdown review summary for approve/request_changes",
-			}),
-		),
-		comment: Type.Optional(
-			Type.String({ description: "Markdown note for discard" }),
-		),
-		commit_message: Type.Optional(
-			Type.String({
-				description: "Commit message for merge (required by squash merges)",
-			}),
-		),
-		file: Type.Optional(
-			Type.String({ description: "add_code_comment: file path in the PR patch" }),
-		),
+		description: Type.Optional(Type.String()),
+		content: Type.Optional(Type.String()),
+		summary: Type.Optional(Type.String()),
+		comment: Type.Optional(Type.String()),
+		commit_message: Type.Optional(Type.String()),
+		file: Type.Optional(Type.String()),
 		from_line: Type.Optional(
-			Type.Integer({
-				minimum: 1,
-				description: "add_code_comment: 1-based start line (right side of patch)",
-			}),
-		),
-		to_line: Type.Optional(
-			Type.Integer({
-				minimum: 1,
-				description: "add_code_comment: 1-based end line; defaults to from_line",
-			}),
-		),
-		comment_id: Type.Optional(
-			Type.Integer({
-				minimum: 1,
-				description:
-					"Code comment id for reply_code_comment, resolve_code_comment, or unresolve_code_comment",
-			}),
+			Type.Integer({ minimum: 1, description: "Right-side line" }),
 		),
+		to_line: Type.Optional(Type.Integer({ minimum: 1 })),
+		comment_id: Type.Optional(Type.Integer({ minimum: 1 })),
 		source_branch: Type.Optional(Type.String()),
 		target_branch: Type.Optional(Type.String()),
 		source_project: Type.Optional(Type.String()),
 		target_project: Type.Optional(Type.String()),
-		assignees: Type.Optional(
-			Type.Array(Type.String(), { description: "User logins, repeatable" }),
-		),
-		reviewers: Type.Optional(
-			Type.Array(Type.String(), { description: "User logins, repeatable" }),
-		),
-		remove_reviewers: Type.Optional(
-			Type.Array(Type.String(), { description: "edit: user logins to remove" }),
-		),
+		assignees: Type.Optional(Type.Array(Type.String())),
+		reviewers: Type.Optional(Type.Array(Type.String())),
+		remove_reviewers: Type.Optional(Type.Array(Type.String())),
 		labels: Type.Optional(
-			Type.Array(Type.String(), {
-				description: "Label names; discover via valid_labels",
-			}),
+			Type.Array(Type.String(), { description: "Use valid_labels" }),
 		),
 		merge_strategy: Type.Optional(Type.String()),
 		auto_merge: Type.Optional(Type.Boolean()),
 		auto_merge_commit_message: Type.Optional(Type.String()),
 		for_code_review: Type.Optional(
-			Type.Boolean({ description: "get_patch: review-scoped patch" }),
+			Type.Boolean({ description: "Review-scoped patch" }),
 		),
 		for_write: Type.Optional(
-			Type.Boolean({ description: "checkout: set up the branch for pushing" }),
+			Type.Boolean({ description: "Prepare checkout for push" }),
 		),
 		project: Type.Optional(
-			Type.String({
-				description: "Project path for list; defaults to the current project",
-			}),
+			Type.String({ description: "Default: current project" }),
 		),
 		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>;
 
 	pi.registerTool({
 		name: "onedev_pull",
 		label: "OneDev Pull Requests",
-		description:
-			"Read and edit OneDev pull requests: metadata, labels, comments, line-anchored code comments, builds, patch, review outcomes, and guarded merge/discard. Runs in the current repository's project.",
+		description: "Read/manage OneDev PRs, patch, comments, reviews, and guarded merge.",
 		parameters,
 		async execute(_toolCallId, params: Params, signal, _onUpdate, ctx) {
 			const args = buildPullArgs(params);
@@ -334,7 +304,22 @@ export function registerPullTool(pi: ExtensionAPI, deps: ToolDeps): void {
 					signal,
 				});
 			}
-			const output = await runInContext(deps, args, { signal });
+			const output =
+				params.action === "list"
+					? await runListInContext(deps, args, {
+							signal,
+							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),
 				{

package/src/tools/watch.ts

@@ -11,8 +11,7 @@ export function registerWatchTool(
 	pi.registerTool({
 		name: "onedev_watch",
 		label: "OneDev Watch",
-		description:
-			"Create session-scoped one-shot watches for a build result or pull-request attention, or list/stop active watches. Notifications contain bounded metadata; use read tools for details.",
+		description: "Start/list/stop one-shot build or PR-attention watches.",
 		parameters: Type.Object(
 			{
 				action: StringEnum([
@@ -21,12 +20,8 @@ export function registerWatchTool(
 					"list",
 					"stop",
 				]),
-				ref: Type.Optional(
-					Type.String({ description: "Build or pull request reference to watch" }),
-				),
-				watch_id: Type.Optional(
-					Type.String({ description: "Watch id required by stop" }),
-				),
+				ref: Type.Optional(Type.String()),
+				watch_id: Type.Optional(Type.String()),
 				interval_seconds: Type.Optional(
 					Type.Integer({ minimum: 15, maximum: 300, default: 30 }),
 				),