Skip to content

armgit / Orkas

Public Imported from GitHub
0

Orkas is an open-source (MIT), local-first AI team for your desktop: a Commander turns your goal into to-dos and coordinates 16 built-in specialist agents plus Claude Code, Codex, OpenCode, OpenClaw and Hermes, with projects, scheduled automations and connectors. Free app for macOS & Windows; built-in models or your own keys.

Harden repository, web and native search tool results

wyt52e41b298f8c
diff --git a/src/core-agent/src/tools/github-repository-fetch.ts b/src/core-agent/src/tools/github-repository-fetch.ts
index 4874898c..b0d0429b 100644
--- a/src/core-agent/src/tools/github-repository-fetch.ts
+++ b/src/core-agent/src/tools/github-repository-fetch.ts
@@ -29,6 +29,16 @@ export type GitHubRepositoryResource = {
owner: string;
repo: string;
canonicalUrl: string;
+ /** Only the exact default API endpoints are represented by a root snapshot. */
+ snapshotComponent?: "metadata" | "readme";
+};
+
+type GitHubSnapshotComponent = { ok: true } | { ok: false; error: string };
+
+/** Component facts stay in the run cache, outside the model-visible result. */
+export type GitHubRepositorySnapshot = {
+ result: ToolResult;
+ components: Record<"metadata" | "readme", GitHubSnapshotComponent>;
};
function safePathPart(value: string): string | null {
@@ -84,6 +94,10 @@ export function identifyGitHubRepositoryResource(rawUrl: string): GitHubReposito
owner,
repo,
canonicalUrl: `https://github.com/${owner}/${repo}`,
+ ...(parsed.origin === "https://api.github.com" && !parsed.search && !parsed.username && !parsed.password
+ && kind !== "repository"
+ && parsed.pathname === `/repos/${ownerPart}/${repoPart}${kind === "readme" ? "/readme" : ""}`
+ ? { snapshotComponent: kind } : {}),
};
}
@@ -316,8 +330,15 @@ export function renderGitHubSnapshotView(
export async function fetchGitHubRepositorySnapshot(
resource: GitHubRepositoryResource,
signal?: AbortSignal,
-): Promise<ToolResult> {
- const cancelled = (): ToolResult => ({
+): Promise<GitHubRepositorySnapshot> {
+ const failed = (result: ToolResult): GitHubRepositorySnapshot => ({
+ result,
+ components: {
+ metadata: { ok: false, error: result.content },
+ readme: { ok: false, error: result.content },
+ },
+ });
+ const cancelled = (): GitHubRepositorySnapshot => failed({
content: `Fetch of ${resource.canonicalUrl} was cancelled`,
isError: true,
});
@@ -352,12 +373,18 @@ export async function fetchGitHubRepositorySnapshot(
if ("error" in metadataBody && "error" in readmeBody) {
return {
- content: [
- `Error fetching structured GitHub repository snapshot for ${resource.canonicalUrl}`,
- `Metadata: ${metadataBody.error}`,
- `README: ${readmeBody.error}`,
- ].join("\n"),
- isError: true,
+ result: {
+ content: [
+ `Error fetching structured GitHub repository snapshot for ${resource.canonicalUrl}`,
+ `Metadata: ${metadataBody.error}`,
+ `README: ${readmeBody.error}`,
+ ].join("\n"),
+ isError: true,
+ },
+ components: {
+ metadata: { ok: false, error: metadataBody.error },
+ readme: { ok: false, error: readmeBody.error },
+ },
};
}
@@ -365,7 +392,12 @@ export async function fetchGitHubRepositorySnapshot(
let metadataWarning: string | null = null;
if ("raw" in metadataBody) {
try {
- metadata = JSON.parse(metadataBody.raw) as GitHubMetadata;
+ const decoded: unknown = JSON.parse(metadataBody.raw);
+ if (!decoded || typeof decoded !== "object" || Array.isArray(decoded)) {
+ metadataWarning = "GitHub metadata response was not a JSON object";
+ } else {
+ metadata = decoded as GitHubMetadata;
+ }
} catch {
metadataWarning = "GitHub metadata response was not valid JSON";
}
@@ -388,6 +420,7 @@ export async function fetchGitHubRepositorySnapshot(
// Keep the complete README in the run-cached result. web_fetch fits it
// into each call's maxChars and serves later windows by offset.
readme = normalizeGitHubReadme(readme);
+ if (!readme) readmeWarning = "GitHub README response was empty";
} else {
readmeWarning = readmeBody.error;
}
@@ -401,46 +434,53 @@ export async function fetchGitHubRepositorySnapshot(
...(readmeWarning ? [`- README unavailable: ${readmeWarning}`] : []),
];
return {
- content: [
- `Title: ${metadataValue(metadata.full_name)}`,
- `URL: ${resource.canonicalUrl}`,
- `Accessed at: ${new Date().toISOString()}`,
- "Source type: structured GitHub repository snapshot",
- `GitHub metadata API: ${metadataUrl}`,
- `GitHub README API: ${readmeUrl}`,
- "",
- "Repository metadata (authoritative GitHub API values at access time):",
- `- Full name: ${metadataValue(metadata.full_name)}`,
- `- Description: ${metadataValue(metadata.description)}`,
- `- License name: ${metadataValue(license?.name)}`,
- `- License SPDX ID: ${metadataValue(license?.spdx_id)}`,
- `- License API URL: ${metadataValue(license?.url)}`,
- `- Created at: ${metadataValue(metadata.created_at)}`,
- `- Updated at: ${metadataValue(metadata.updated_at)}`,
- `- Pushed at: ${metadataValue(metadata.pushed_at)}`,
- `- Archived: ${metadataValue(metadata.archived)}`,
- `- Fork: ${metadataValue(metadata.fork)}`,
- `- Default branch: ${metadataValue(metadata.default_branch)}`,
- `- Stars: ${metadataValue(metadata.stargazers_count)}`,
- `- Forks: ${metadataValue(metadata.forks_count)}`,
- `- Open issues: ${metadataValue(metadata.open_issues_count)}`,
- `- Homepage: ${metadataValue(metadata.homepage)}`,
- `- Topics: ${topics || "Not provided"}`,
- ...(warnings.length ? ["", "Snapshot warnings:", ...warnings] : []),
- "",
- GITHUB_README_MARKER,
- readme || "README unavailable; do not infer README-backed claims.",
- ].join("\n"),
+ components: {
+ metadata: metadataWarning ? { ok: false, error: metadataWarning } : { ok: true },
+ readme: readmeWarning ? { ok: false, error: readmeWarning } : { ok: true },
+ },
+ result: {
+ ...(metadataWarning && readmeWarning ? { isError: true } : {}),
+ content: [
+ `Title: ${metadataValue(metadata.full_name)}`,
+ `URL: ${resource.canonicalUrl}`,
+ `Accessed at: ${new Date().toISOString()}`,
+ "Source type: structured GitHub repository snapshot",
+ `GitHub metadata API: ${metadataUrl}`,
+ `GitHub README API: ${readmeUrl}`,
+ "",
+ "Repository metadata (authoritative GitHub API values at access time):",
+ `- Full name: ${metadataValue(metadata.full_name)}`,
+ `- Description: ${metadataValue(metadata.description)}`,
+ `- License name: ${metadataValue(license?.name)}`,
+ `- License SPDX ID: ${metadataValue(license?.spdx_id)}`,
+ `- License API URL: ${metadataValue(license?.url)}`,
+ `- Created at: ${metadataValue(metadata.created_at)}`,
+ `- Updated at: ${metadataValue(metadata.updated_at)}`,
+ `- Pushed at: ${metadataValue(metadata.pushed_at)}`,
+ `- Archived: ${metadataValue(metadata.archived)}`,
+ `- Fork: ${metadataValue(metadata.fork)}`,
+ `- Default branch: ${metadataValue(metadata.default_branch)}`,
+ `- Stars: ${metadataValue(metadata.stargazers_count)}`,
+ `- Forks: ${metadataValue(metadata.forks_count)}`,
+ `- Open issues: ${metadataValue(metadata.open_issues_count)}`,
+ `- Homepage: ${metadataValue(metadata.homepage)}`,
+ `- Topics: ${topics || "Not provided"}`,
+ ...(warnings.length ? ["", "Snapshot warnings:", ...warnings] : []),
+ "",
+ GITHUB_README_MARKER,
+ readme || "README unavailable; do not infer README-backed claims.",
+ ].join("\n"),
+ },
};
} catch (error) {
if (signal?.aborted) return cancelled();
const message = error instanceof Error ? error.message : String(error);
- return {
+ return failed({
content: message.includes("abort")
? `Timeout fetching structured GitHub repository snapshot (${DEFAULT_WEB_FETCH_TIMEOUT_MS}ms)`
: `Error fetching structured GitHub repository snapshot: ${message}`,
isError: true,
- };
+ });
} finally {
clearTimeout(timer);
signal?.removeEventListener("abort", onAbort);
@@ -450,11 +490,12 @@ export async function fetchGitHubRepositorySnapshot(
}
export function compactGitHubSnapshotReplay(resource: GitHubRepositoryResource): ToolResult {
+ const component = resource.snapshotComponent === "metadata" ? "metadata" : "README";
return {
content: [
- "GITHUB_REPOSITORY_SNAPSHOT_CACHE_HIT: this repository's metadata and README were already fetched in this run; no network request was made.",
+ `GITHUB_REPOSITORY_SNAPSHOT_CACHE_HIT: this repository's requested ${component} was already fetched in this run; no network request was made.`,
`URL: ${resource.canonicalUrl}`,
- "Use the earlier structured repository snapshot and durable evidence ledger. Do not fetch a GitHub HTML/API/README alias again; to read more of the README, call web_fetch on the repository URL with the offset its snapshot reported.",
+ "Use the earlier structured repository snapshot and durable evidence ledger. To read more of the snapshot, call web_fetch on the repository URL with the offset it reported.",
].join("\n"),
};
}
diff --git a/src/core-agent/src/tools/web-fetch.ts b/src/core-agent/src/tools/web-fetch.ts
index c08dce20..50f07a45 100644
--- a/src/core-agent/src/tools/web-fetch.ts
+++ b/src/core-agent/src/tools/web-fetch.ts
@@ -12,6 +12,7 @@ import {
fetchGitHubRepositorySnapshot,
identifyGitHubRepositoryResource,
renderGitHubSnapshotView,
+ type GitHubRepositorySnapshot,
} from "./github-repository-fetch.js";
import {
DEFAULT_WEB_FETCH_TIMEOUT_MS,
@@ -56,6 +57,7 @@ export function configureWebFetchRenderer(renderer: WebFetchRenderer | null): vo
type WebFetchCacheEntry = {
epoch: number;
result: Promise<ToolResult>;
+ githubSnapshot?: Promise<GitHubRepositorySnapshot>;
/** End of the furthest character range already returned for this URL. After
* context compaction, only windows at or beyond it are served again. */
servedThrough?: number;
@@ -842,6 +844,7 @@ export const webFetchTool: AgentTool = defineTool({
}
const offset = parseOffset(input.offset);
if (typeof offset === "string") return { content: offset, isError: true };
+ if (ctx.signal?.aborted) return { content: `Fetch of ${url} was cancelled`, isError: true };
const fetchCache = fetchCacheForState(ctx.state);
const failurePolicy = failurePolicyForState(ctx.state);
@@ -875,18 +878,21 @@ export const webFetchTool: AgentTool = defineTool({
return compactReplay ? compactCacheReplay(result, servedThrough) : serveView(cached, result);
}
- const priorGitHubSnapshot = githubResource
- ? fetchCache.get(`github:${githubResource.key}`)
+ const priorGitHubSnapshot = githubResource?.snapshotComponent
+ ? fetchCache.get(`github:${githubResource.key}`)?.githubSnapshot
: undefined;
- if (githubResource && githubResource.kind !== "repository" && priorGitHubSnapshot) {
- // A pending or failed root fetch is not successful source evidence.
- const result = await priorGitHubSnapshot.result;
- if (result.isError) return applyExplicitCharacterLimit(result, maxChars);
+ if (githubResource?.snapshotComponent && priorGitHubSnapshot) {
+ // Raw URLs and ref/path variants have independent identities. An exact
+ // default API alias may reuse only its own acquired component or failure.
+ const snapshot = await priorGitHubSnapshot;
+ if (ctx.signal?.aborted) return { content: `Fetch of ${url} was cancelled`, isError: true };
+ const component = snapshot.components[githubResource.snapshotComponent];
+ if (component.ok === false) return applyExplicitCharacterLimit({ content: component.error, isError: true }, maxChars);
log.info("github repository alias cache hit; skipped network request", {
repository: githubResource.key,
requestedKind: githubResource.kind,
});
- return compactGitHubSnapshotReplay(githubResource);
+ return applyExplicitCharacterLimit(compactGitHubSnapshotReplay(githubResource), maxChars);
}
if (failurePolicy.blockedAuthOrigins.has(origin)) {
@@ -899,10 +905,13 @@ export const webFetchTool: AgentTool = defineTool({
};
}
- const request = githubResource?.kind === "repository"
+ const snapshotRequest = githubResource?.kind === "repository"
? fetchGitHubRepositorySnapshot(githubResource, ctx.signal)
+ : undefined;
+ const request = snapshotRequest
+ ? snapshotRequest.then(snapshot => snapshot.result)
: fetchGeneralUrl(url, ctx.signal);
- const cacheEntry: WebFetchCacheEntry = { epoch, result: request };
+ const cacheEntry: WebFetchCacheEntry = { epoch, result: request, githubSnapshot: snapshotRequest };
fetchCache.set(requestKey, cacheEntry);
let result = await request;
const disposition = fetchFailureDisposition(result);
diff --git a/src/core-agent/test/github-repository-fetch.test.ts b/src/core-agent/test/github-repository-fetch.test.ts
index 1e2c1396..77ad4ef2 100644
--- a/src/core-agent/test/github-repository-fetch.test.ts
+++ b/src/core-agent/test/github-repository-fetch.test.ts
@@ -8,6 +8,7 @@ import { getBuiltinTools } from "../src/tools/index.js";
const REPOSITORY_URL = "https://github.com/example/project";
const METADATA_URL = "https://api.github.com/repos/example/project";
const README_URL = `${METADATA_URL}/readme`;
+const RAW_URL = "https://raw.githubusercontent.com/example/project/main/README.md";
const metadata = {
full_name: "example/project",
@@ -51,6 +52,192 @@ afterEach(() => {
});
describe("GitHub repository web_fetch provider", () => {
+ it.each([false, true])("fetches an independent raw source after a denied root (in flight: %s)", async inFlight => {
+ let release!: () => void;
+ const gate = new Promise<void>(resolve => { release = resolve; });
+ const fetchMock = vi.fn(async (input: string | URL | Request) => {
+ if (requestUrl(input) === RAW_URL) return textResponse("# Independent README\nRecovered source.");
+ if (inFlight) await gate;
+ return textResponse("Forbidden", 403);
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ const webFetch = getBuiltinTools().find(tool => tool.name === "web_fetch")!;
+ const context = { state: { runScopedLedger: new Map() } };
+ const root = webFetch.execute({ url: REPOSITORY_URL }, context);
+ if (!inFlight) await root;
+ const raw = webFetch.execute({ url: RAW_URL }, context);
+ try {
+ // The raw host must be contacted even while GitHub's API is still pending.
+ await vi.waitFor(() => expect(fetchMock.mock.calls.some(([url]) => requestUrl(url) === RAW_URL)).toBe(true), { timeout: 150 });
+ } finally {
+ release();
+ await root;
+ await raw;
+ }
+ expect((await root).isError).toBe(true);
+ expect((await raw).isError).toBeUndefined();
+ expect((await raw).content).toContain("Recovered source.");
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+ });
+
+ it.each(["readme", "metadata"] as const)("reuses only the acquired component when %s fails", async failed => {
+ const fetchMock = vi.fn(async (input: string | URL | Request) => {
+ const url = requestUrl(input);
+ if (url === METADATA_URL) return failed === "metadata" ? textResponse("unavailable", 503) : jsonResponse(metadata);
+ if (url === README_URL) return failed === "readme" ? textResponse("unavailable", 503) : textResponse("# Acquired README");
+ if (url === RAW_URL) return textResponse("# Raw recovery");
+ throw new Error(`unexpected request: ${url}`);
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ const webFetch = getBuiltinTools().find(tool => tool.name === "web_fetch")!;
+ const context = { state: {} };
+ const snapshot = await webFetch.execute({ url: REPOSITORY_URL }, context);
+ const missing = await webFetch.execute({ url: failed === "readme" ? README_URL : METADATA_URL }, context);
+ const acquired = await webFetch.execute({ url: failed === "readme" ? METADATA_URL : README_URL }, context);
+ const raw = await webFetch.execute({ url: RAW_URL }, context);
+ expect(snapshot.isError).toBeUndefined();
+ expect(snapshot.content).toContain("unavailable: HTTP 503");
+ expect(missing.isError).toBe(true);
+ expect(missing.content).toContain("HTTP 503");
+ expect(missing.content).not.toContain("GITHUB_REPOSITORY_SNAPSHOT_CACHE_HIT");
+ expect(acquired.isError).toBeUndefined();
+ expect(acquired.content).toContain("GITHUB_REPOSITORY_SNAPSHOT_CACHE_HIT");
+ expect(acquired.content).not.toContain("metadata and README were already fetched");
+ expect(raw.content).toBe("# Raw recovery");
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+ });
+
+ it("keeps raw refs, nested paths and API ref queries independent while deduplicating exact URLs", async () => {
+ const sources = new Map([
+ [RAW_URL, "# Main source"],
+ [RAW_URL.replace("/main/", "/release/"), "# Release source"],
+ [RAW_URL.replace("/README.md", "/docs/README.md"), "# Nested source"],
+ [`${README_URL}?ref=release`, "# API release source"],
+ ]);
+ const fetchMock = vi.fn(async (input: string | URL | Request) => {
+ const url = requestUrl(input);
+ if (url === METADATA_URL) return jsonResponse(metadata);
+ if (url === README_URL) return textResponse("# Default snapshot source");
+ if (sources.has(url)) return textResponse(sources.get(url)!);
+ throw new Error(`unexpected request: ${url}`);
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ const webFetch = getBuiltinTools().find(tool => tool.name === "web_fetch")!;
+ const runScopedLedger = new Map();
+ await webFetch.execute({ url: REPOSITORY_URL }, { state: { runScopedLedger } });
+ for (const [url, body] of sources) {
+ const [first, duplicate] = await Promise.all([
+ webFetch.execute({ url }, { state: { runScopedLedger } }),
+ webFetch.execute({ url: `${url}#section` }, { state: { runScopedLedger } }),
+ ]);
+ expect(first.isError).toBeUndefined();
+ expect(first.content).toBe(body);
+ expect(duplicate.content).toBe(body);
+ }
+ expect(fetchMock).toHaveBeenCalledTimes(6);
+ const otherRun = await webFetch.execute({ url: RAW_URL }, { state: {} });
+ expect(otherRun.content).toBe(sources.get(RAW_URL));
+ expect(fetchMock).toHaveBeenCalledTimes(7);
+ });
+
+ it.each([403, 503])("preserves the raw URL's own failure policy after root success (HTTP %s)", async status => {
+ const fetchMock = vi.fn(async (input: string | URL | Request) => {
+ const url = requestUrl(input);
+ if (url === METADATA_URL) return jsonResponse(metadata);
+ if (url === README_URL) return textResponse("# Default README");
+ return textResponse("failed", status);
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ const webFetch = getBuiltinTools().find(tool => tool.name === "web_fetch")!;
+ const context = { state: {} };
+ await webFetch.execute({ url: REPOSITORY_URL }, context);
+ const first = await webFetch.execute({ url: RAW_URL }, context);
+ const second = await webFetch.execute({ url: RAW_URL }, context);
+ const third = await webFetch.execute({ url: RAW_URL }, context);
+ expect(first.isError).toBe(true);
+ expect(first.content).toContain(`HTTP ${status}`);
+ expect(third.content).toContain("E_WEB_FETCH_NONRETRYABLE_CACHE_HIT");
+ if (status === 503) expect(second.content).toContain("E_WEB_FETCH_RETRY_LIMIT");
+ else expect(second.content).toContain("E_WEB_FETCH_NONRETRYABLE_CACHE_HIT");
+ expect(fetchMock).toHaveBeenCalledTimes(status === 503 ? 4 : 3);
+ });
+
+ it("does not contact raw sources after cancellation, even with a cached root", async () => {
+ const fetchMock = vi.fn(async (input: string | URL | Request) => requestUrl(input) === METADATA_URL
+ ? jsonResponse(metadata) : textResponse("# Default README"));
+ vi.stubGlobal("fetch", fetchMock);
+ const webFetch = getBuiltinTools().find(tool => tool.name === "web_fetch")!;
+ const context = { state: {} };
+ await webFetch.execute({ url: REPOSITORY_URL }, context);
+ const controller = new AbortController();
+ controller.abort();
+ const result = await webFetch.execute({ url: RAW_URL }, { ...context, signal: controller.signal });
+ expect(result.isError).toBe(true);
+ expect(result.content).toContain("cancelled");
+ expect(fetchMock).toHaveBeenCalledTimes(2);
+ });
+
+ it.each([
+ ["metadata", "invalid JSON"],
+ ["metadata", "null"],
+ ["readme", " \n\t"],
+ ] as const)("does not certify an unusable %s component (%j)", async (component, body) => {
+ const failedUrl = component === "metadata" ? METADATA_URL : README_URL;
+ vi.stubGlobal("fetch", vi.fn(async (input: string | URL | Request) => {
+ if (requestUrl(input) === failedUrl) return textResponse(body);
+ return component === "metadata" ? textResponse("# Available README") : jsonResponse(metadata);
+ }));
+ const webFetch = getBuiltinTools().find(tool => tool.name === "web_fetch")!;
+ const context = { state: {} };
+ const root = await webFetch.execute({ url: REPOSITORY_URL }, context);
+ const unusable = await webFetch.execute({ url: failedUrl }, context);
+ const available = await webFetch.execute({ url: component === "metadata" ? README_URL : METADATA_URL }, context);
+ expect(root.isError).toBeUndefined();
+ expect(root.content).toContain(component === "metadata" ? "# Available README" : "- Full name: example/project");
+ expect(unusable.isError).toBe(true);
+ expect(unusable.content).not.toContain("GITHUB_REPOSITORY_SNAPSHOT_CACHE_HIT");
+ expect(available.isError).toBeUndefined();
+ expect(available.content).toContain("GITHUB_REPOSITORY_SNAPSHOT_CACHE_HIT");
+ });
+
+ it("cancels an active independent raw request and releases its deadline", async () => {
+ vi.useFakeTimers();
+ let rawSignal: AbortSignal | undefined;
+ const fetchMock = vi.fn((input: string | URL | Request, init: RequestInit) => {
+ const url = requestUrl(input);
+ if (url === METADATA_URL) return Promise.resolve(jsonResponse(metadata));
+ if (url === README_URL) return Promise.resolve(textResponse("# Default README"));
+ rawSignal = init.signal!;
+ return new Promise<Response>((_resolve, reject) => {
+ rawSignal!.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")), { once: true });
+ });
+ });
+ vi.stubGlobal("fetch", fetchMock);
+ const webFetch = getBuiltinTools().find(tool => tool.name === "web_fetch")!;
+ const context = { state: {} };
+ await webFetch.execute({ url: REPOSITORY_URL }, context);
+ const controller = new AbortController();
+ const pending = webFetch.execute({ url: RAW_URL }, { ...context, signal: controller.signal });
+ controller.abort();
+ const result = await pending;
+ expect(rawSignal?.aborted).toBe(true);
+ expect(result.isError).toBe(true);
+ expect(result.content).toContain("cancelled");
+ expect(fetchMock).toHaveBeenCalledTimes(3);
+ expect(vi.getTimerCount()).toBe(0);
+ });
+
+ it("fails a snapshot with no usable components even when both HTTP responses are successful", async () => {
+ vi.stubGlobal("fetch", vi.fn(async (input: string | URL | Request) => textResponse(
+ requestUrl(input) === METADATA_URL ? "invalid JSON" : " \n\t",
+ )));
+ const webFetch = getBuiltinTools().find(tool => tool.name === "web_fetch")!;
+ const result = await webFetch.execute({ url: REPOSITORY_URL }, { state: {} });
+ expect(result.isError).toBe(true);
+ expect(result.content).toContain("Metadata unavailable: GitHub metadata response was not valid JSON");
+ expect(result.content).toContain("README unavailable: GitHub README response was empty");
+ });
+
it.each([false, true])("does not claim cached source evidence after a denied repository fetch (in flight: %s)", async inFlight => {
let release!: () => void;
const gate = new Promise<void>(resolve => { release = resolve; });
@@ -95,7 +282,7 @@ describe("GitHub repository web_fetch provider", () => {
siblingSignal!.addEventListener("abort", () => reject(new DOMException("aborted", "AbortError")), { once: true });
});
}));
- const result = await fetchGitHubRepositorySnapshot(repositoryResource());
+ const { result } = await fetchGitHubRepositorySnapshot(repositoryResource());
expect(result.isError).toBe(true);
expect(siblingSignal?.aborted).toBe(true);
});
@@ -147,7 +334,7 @@ describe("GitHub repository web_fetch provider", () => {
});
vi.stubGlobal("fetch", fetchMock);
- const result = await fetchGitHubRepositorySnapshot(repositoryResource());
+ const { result } = await fetchGitHubRepositorySnapshot(repositoryResource());
expect(result.isError).toBeUndefined();
expect(result.content).toContain("Title: example/project");
@@ -166,7 +353,7 @@ describe("GitHub repository web_fetch provider", () => {
});
vi.stubGlobal("fetch", fetchMock);
- const result = await fetchGitHubRepositorySnapshot(repositoryResource());
+ const { result } = await fetchGitHubRepositorySnapshot(repositoryResource());
expect(result.isError).toBeUndefined();
expect(result.content).toContain("Title: Not provided");
@@ -232,7 +419,7 @@ describe("GitHub repository web_fetch provider", () => {
});
vi.stubGlobal("fetch", fetchMock);
- const result = await fetchGitHubRepositorySnapshot(repositoryResource());
+ const { result } = await fetchGitHubRepositorySnapshot(repositoryResource());
expect(result.isError).toBeUndefined();
expect(result.content).toContain(readme);
diff --git a/src/main/model/core-agent/native-search-tools.ts b/src/main/model/core-agent/native-search-tools.ts
index f771606b..e256d656 100644
--- a/src/main/model/core-agent/native-search-tools.ts
+++ b/src/main/model/core-agent/native-search-tools.ts
@@ -78,9 +78,11 @@ const OPENAI_SEARCH_MODELS = new Set([
'gpt-5', 'gpt-5-mini', 'gpt-5-nano', 'gpt-5.1', 'gpt-5.2', 'gpt-5.3-codex',
'gpt-5.4', 'gpt-5.5', 'gpt-5.6', 'gpt-5.6-sol', 'gpt-5.6-terra', 'gpt-5.6-luna', 'gpt-6-astra',
]);
-// Tool combinations are supported only by documented Gemini 3 models.
+// Tool combinations are supported by documented Gemini 3 and 4 models.
+// Gemini 4 Argon checked 2026-10-19.
// https://ai.google.dev/gemini-api/docs/generate-content/tool-combination
const GOOGLE_SEARCH_MODELS = new Set([
+ 'gemini-4-argon',
'gemini-3-flash-preview', 'gemini-3.1-pro-preview',
'gemini-3.1-flash-lite-preview', 'gemini-3.1-flash-lite',
'gemini-3.5-flash', 'gemini-3.5-flash-lite', 'gemini-3.6-flash', 'gemini-3.7-flash', 'gemini-3.8-flash',
diff --git a/src/main/model/core-agent/search-file-result.ts b/src/main/model/core-agent/search-file-result.ts
index e42ae470..18030bb1 100644
--- a/src/main/model/core-agent/search-file-result.ts
+++ b/src/main/model/core-agent/search-file-result.ts
@@ -16,7 +16,8 @@ export interface SearchFileHit {
* JSON escaping preserves filenames that contain delimiters or newlines. */
export function formatSearchFileResults(
hits: readonly SearchFileHit[],
- filesystemPaths: Pick<typeof path, 'relative'> = path,
+ filesystemPaths: Pick<typeof path, 'relative' | 'isAbsolute' | 'sep'> = path,
+ workingDir?: string,
): string {
const roots: string[] = [];
const rootIndexes = new Map<string, number>();
@@ -28,10 +29,18 @@ export function formatSearchFileResults(
roots.push(hit.root);
}
// Logical Skill addresses always use '/', including on Windows hosts.
- const paths = hit.root.startsWith('@skill/') ? path.posix : filesystemPaths;
+ const skillPath = hit.root.startsWith('@skill/');
+ const paths = skillPath ? path.posix : filesystemPaths;
+ let readPath = hit.path;
+ if (!skillPath && workingDir) {
+ const relative = filesystemPaths.relative(workingDir, hit.path);
+ if (relative !== '..' && !relative.startsWith(`..${filesystemPaths.sep}`)
+ && !filesystemPaths.isAbsolute(relative)) readPath = relative || '.';
+ }
return JSON.stringify({
root,
path: paths.relative(hit.root, hit.path),
+ read_path: readPath,
name: hit.name,
size: hit.size,
mtime: new Date(hit.mtime).toISOString(),
@@ -39,6 +48,6 @@ export function formatSearchFileResults(
...(hit.totalChars !== undefined ? { total_chars: hit.totalChars } : {}),
});
});
- return 'File paths are relative to roots[file.root] (zero-based); join the root and path to read a file.\n'
+ return 'Use files[].read_path directly for file tools. files[].path is relative to roots[file.root] (zero-based).\n'
+ `{"roots":${JSON.stringify(roots)},"files":[\n${files.join(',\n')}\n]}`;
}
diff --git a/test/main/model/core-agent/search-file-result.test.ts b/test/main/model/core-agent/search-file-result.test.ts
index afd263fd..f00119be 100644
--- a/test/main/model/core-agent/search-file-result.test.ts
+++ b/test/main/model/core-agent/search-file-result.test.ts
@@ -14,17 +14,19 @@ describe('search_files root-relative output', () => {
...hit(root, `${root}readings/${i}.jsonl`), name: `${i}.jsonl`,
...(i === 0 ? { totalChars: 0 } : {}),
}));
- const output = formatSearchFileResults(hits, path.posix);
+ const output = formatSearchFileResults(hits, path.posix, root);
const result = parse(output);
expect(result.roots).toEqual([root]);
expect(output.split(root)).toHaveLength(2);
expect(result.files).toEqual(hits.map((h, i) => ({
- root: 0, path: `readings/${i}.jsonl`, name: h.name, size: h.size,
+ root: 0, path: `readings/${i}.jsonl`, read_path: `readings/${i}.jsonl`, name: h.name, size: h.size,
mtime: new Date(h.mtime).toISOString(), source: h.source,
...(h.totalChars !== undefined ? { total_chars: h.totalChars } : {}),
})));
expect(result.files.map((f: any) => path.posix.join(result.roots[f.root], f.path)))
.toEqual(hits.map((h) => h.path));
+ expect(result.files.map((f: any) => path.posix.resolve(root, f.read_path)))
+ .toEqual(hits.map((h) => h.path));
const old = hits.map((h) => `- ${h.name} (path=${h.path}, size=${h.size}, mtime=${new Date(h.mtime).toISOString()}, source=${h.source}${h.totalChars !== undefined ? `, total_chars=${h.totalChars}` : ''})`).join('\n');
expect(output.length).toBeLessThan(old.length);
});
@@ -42,6 +44,7 @@ describe('search_files root-relative output', () => {
expect(result.files.map((f: any) => f.root)).toEqual([0, 1, 0]);
expect(result.files.map((f: any) => paths.join(result.roots[f.root], f.path)))
.toEqual(hits.map((h) => h.path));
+ expect(result.files.map((f: any) => f.read_path)).toEqual(hits.map((h) => h.path));
expect(result.files.map((f: any) => f.source)).toEqual(['workspace', 'attachment', 'workspace']);
});
@@ -51,6 +54,7 @@ describe('search_files root-relative output', () => {
const result = parse(formatSearchFileResults([{ ...hit(root, `${root}/${name}`), name }], path.posix));
expect(result.roots).toEqual([root]);
expect(result.files[0].path).toBe(name);
+ expect(result.files[0].read_path).toBe(`${root}/${name}`);
expect(result.files[0].name).toBe(name);
});
@@ -59,6 +63,31 @@ describe('search_files root-relative output', () => {
const result = parse(formatSearchFileResults([hit(root, `${root}/facts.md`, 'extra')], path.win32));
expect(result.roots).toEqual([root]);
expect(result.files[0].path).toBe('facts.md');
+ expect(result.files[0].read_path).toBe('@skill/bundle/references/facts.md');
expect(path.posix.join(result.roots[0], result.files[0].path)).toBe('@skill/bundle/references/facts.md');
});
+
+ it.each([
+ ['POSIX', path.posix, '/workspace/project', '/attachments/chat'],
+ ['Windows drives', path.win32, 'C:\\workspace\\project', 'D:\\attachments\\chat'],
+ ['Windows UNC', path.win32, '\\\\server\\share\\project', '\\\\server\\other\\chat'],
+ ] as const)('provides directly readable %s paths from a nested working directory', (_label, paths, root, attachments) => {
+ const cwd = paths.join(root, 'conversation');
+ const hits = [
+ hit(root, paths.join(cwd, 'accounts.csv')),
+ hit(root, paths.join(cwd, 'conversation', 'accounts.csv')),
+ hit(root, paths.join(root, 'conversation-other', 'accounts.csv')),
+ hit(attachments, paths.join(attachments, 'accounts.csv'), 'attachment'),
+ ];
+ const output = formatSearchFileResults(hits, paths, cwd);
+ const result = parse(output);
+ expect(result.files.map((f: any) => f.read_path)).toEqual([
+ 'accounts.csv', paths.join('conversation', 'accounts.csv'), hits[2].path, hits[3].path,
+ ]);
+ expect(result.files.map((f: any) => paths.resolve(cwd, f.read_path)))
+ .toEqual(hits.map((h) => h.path));
+ expect(result.files.map((f: any) => paths.join(result.roots[f.root], f.path)))
+ .toEqual(hits.map((h) => h.path));
+ expect(output).toContain('Use files[].read_path directly for file tools.');
+ });
});
diff --git a/test/main/model/native-search-tools.test.ts b/test/main/model/native-search-tools.test.ts
index fdcbefc2..2646aadb 100644
--- a/test/main/model/native-search-tools.test.ts
+++ b/test/main/model/native-search-tools.test.ts
@@ -89,6 +89,7 @@ describe('native search eligibility for the actual request model', () => {
expect(nativeSearchToolForModel({ ...model, api: 'openai-completions' }, {})).toBeUndefined();
expect(nativeSearchToolForModel({ api: 'openai-responses' }, {})).toBeUndefined();
expect(nativeSearchToolForModel({ provider: 'google', api: 'google-generative-ai', id: 'gemini-3.8-flash' }, {})).toEqual({ googleSearch: {} });
+ expect(nativeSearchToolForModel({ provider: 'google', api: 'google-generative-ai', id: 'gemini-4-argon' }, {})).toEqual({ googleSearch: {} });
expect(nativeSearchToolForModel({ provider: 'google', api: 'google-generative-ai', id: 'gemini-1.5-pro' }, {})).toBeUndefined();
for (const id of ['gemini-2.5-flash', 'gemini-3-pro-image-preview', 'gemini-3.1-flash-image-preview', 'gemini-unreviewed']) {
expect(nativeSearchToolForModel({ provider: 'google', api: 'google-generative-ai', id }, {})).toBeUndefined();