feat: add Harness File Store support

[sahilharness]

Add File Store resources for metadata, uploads, and content reads through the existing registry-backed MCP tools.

Description

add file store support.
you can now

• list out all files/folders in a scope
• read content from a file
• create a file
• update content from a file
• delete a file

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
2 out of 3 committers have signed the CLA.

✅ thisrohangupta
✅ sahilharness
❌ anishharness
_{You have signed the CLA already but the status is still pending? Let us recheck it.}

[cursor]

Stale comment

1. Medium — src/registry/toolsets/file-store.ts, src/tools/harness-create.ts, src/tools/harness-update.ts, src/tools/harness-delete.ts, src/tools/harness-describe.ts: file_store_item now advertises supportedScopes: ["account", "org", "project"] on a write-capable resource, but the public write tools still do not expose resource_scope and do not opt into URL-derived scope. That means harness_describe tells agents to set resource_scope, yet harness_create / harness_update / harness_delete can only hit account/org File Store writes through undocumented params.resource_scope; with configured defaults they otherwise fall back to project scope. This is a structured discoverability/runtime contract mismatch.
2. Low — src/utils/url-parser.ts, src/registry/toolsets/file-store.ts, tests/utils/url-parser.test.ts: the PR adds File Store URL parsing, but the resource definition still has no deepLinkTemplate, so File Store responses cannot emit openInHarness links even though pasted URLs now parse. There is also no matching url-parser regression coverage for the new file-store segment / URL-default merge path, so this new discoverability surface is one-way and unverified.
3. Low — src/registry/index.ts, README.md: the branch is currently red on pnpm docs:check because adding the new toolset changed the generated resource/toolset counts without regenerating README.md. CI’s pnpm test and pnpm typecheck steps passed on the PR head; docs sync is the remaining failure.

Overall, the File Store endpoint wiring itself is mostly aligned with the repo standards: declarative toolset registration, clean GET vs multipart-body separation, no body leakage in the update preflight, appropriate risk policies, and guarded output shaping for file downloads. The gaps are in shared-tool discoverability / round-trip UX rather than the endpoint mappings themselves.

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

file_store_item is now a write-capable resource that advertises account/org/project scope, but the public write tools still do not publish a top-level resource_scope input and they intentionally ignore URL-derived scope on create/update/delete. That means harness_describe(resource_type='file_store_item') now tells agents they can set resource_scope, while harness_create / harness_update / harness_delete can only reach those paths through undocumented params.resource_scope and otherwise fall back to configured project scope. I think this should either be made schema-visible on the write tools or kept out of the advertised multi-scope contract.

[cursor]

Stale comment

Findings:

1. Medium: file_store_item over-advertises multi-scope writes. The new resource exposes supportedScopes through harness_describe, but the shared write tools still do not accept resource_scope and intentionally do not derive it from write URLs. That means account/org File Store writes are described as supported, but agents cannot actually invoke them through harness_create / harness_update / harness_delete today.
2. Medium: the branch is not merge-ready because generated docs were not refreshed. Both CI jobs fail pnpm docs:check, and I reproduced the same locally after a clean build: README.md is stale. Run \pnpm docs:generate` to refresh.`
3. Low: File Store URL support is currently one-way. The parser knows /file-store/..., but there is no matching regression coverage for that shared parser path, and the resource definition does not add a deepLinkTemplate, so openInHarness cannot round-trip back to the same UI surface.

Assumption:
I’m assuming File Store is intended to follow the same registry contract that harness_describe exposes. If writes are intentionally project-only, the resource metadata should say that explicitly instead of advertising account/org/project support.

Verification:

• pnpm test -> 54 files, 1313 tests passed
• pnpm typecheck -> passed
• pnpm build && pnpm docs:check -> failed (README.md is stale. Run \pnpm docs:generate` to refresh.`)

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

supportedScopes is surfaced through harness_describe, but the shared write tools still don't accept resource_scope and intentionally do not infer it from write URLs. That means this resource now advertises account/org/project support for create / update / delete, while agents can only invoke the default/project scoping path today. Either plumb resource_scope through the write tools or narrow the File Store scope contract to the read operations so the metadata stays honest.

[cursor]

Stale comment

Found 2 issues against Sunil's architecture standards.

1. Medium - README.md's public contract is still incomplete. The PR refreshes the numeric counts, but the visible catalog still does not list the new file-store toolset or the file_store_item / file_store_content resource types, so users and agents cannot actually discover the feature from the docs.
2. Low - The new File Store content safety logic is only partially verified. The added tests cover the happy-path UTF-8 download, but not the large/binary guard branches that prevent oversized or non-text payloads from being inlined.

Assumption: README.md is still intended to be a discoverable public surface, since the repo keeps checking it via scripts/generate-docs.js --check.

Verification run:

• pnpm test tests/registry/file-store.test.ts tests/client/harness-client.test.ts
• pnpm typecheck
• pnpm build
• Simulated scripts/generate-docs.js --check against origin/pr-197's README.md: it passes even though that README currently has zero file-store mentions.

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

This only exercises the small UTF-8 branch of fileStoreContentExtract(). The risky part of the new feature is the guard logic for oversized text and binary payloads (>1MB refusal, base64 fallback for small binary, refusal for large binary), and none of those branches are covered yet. Given the repo's prove it works standard, I'd add focused assertions for those paths before shipping.

[cursor]

Stale comment

Found 3 remaining architecture-contract issues on the current PR head (69fa549). The follow-up commits fixed the earlier README / docs-check drift and added File Store URL-parser coverage, and I re-verified the branch with:

• pnpm test tests/registry/file-store.test.ts tests/client/harness-client.test.ts tests/registry/structural-validation.test.ts tests/utils/url-parser.test.ts
• pnpm typecheck
• pnpm build
• pnpm docs:check

All of those passed, but the File Store metadata layer still overstates or misroutes a few capabilities in ways that will mislead agents using the shared registry surfaces.

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

supportedScopes is resource-wide metadata surfaced through harness_describe, but the public write tools still do not expose a top-level resource_scope input and applyUrlDefaults() only opts read tools into URL-derived scope. That means this resource now advertises account/org/project support for create / update / delete, while agents can only reach those write paths through undocumented params.resource_scope plumbing. I think this should either be surfaced on harness_create / harness_update / harness_delete or narrowed so the advertised scope contract stays honest.

[cursor]

The new deep link doesn't round-trip the File Store routes this PR now teaches the URL parser. tests/utils/url-parser.test.ts recognizes both project URLs like /all/orgs/.../projects/.../setup/resources/file-store/<id> and account URLs like /all/settings/file-store/<id>, but this template always builds the project-scoped collection root and omits the selected file_id. I verified with the repo helper that account scope currently collapses to https://app.harness.io/ng/account/<id>/all/setup/resources/file-store, which doesn't match the account-level route. So openInHarness will be wrong for account-scoped reads and can never deep-link to the specific file that was fetched.

[cursor]

fileStoreUpdateSchema reuses the create fields verbatim, so the structured contract still marks name and type as required even though hydrateFileStoreUpdate() fills them from a metadata lookup and tests/registry/file-store.test.ts intentionally exercises update with only content / mime_type. Because harness_describe exposes bodySchema.fields to agents, this makes the update contract stricter in metadata than it is at runtime.

[cursor]

Stale comment

1. Important — In src/registry/toolsets/file-store.ts, lines 132-133, the file_store_item deep-link template is not round-trip honest for the resource contract. It never includes the item identifier, so every file_store_item result gets a list-page link instead of an item link. It also only models the project-scoped route, while the same resource declares supportedScopes of account/org/project. With the current buildDeepLink() logic in src/utils/deep-links.ts, account-scoped links render as /ng/account/{id}/all/setup/resources/file-store, which does not match the account-level File Store URL shape that the parser/tests accept in src/utils/url-parser.ts and tests/utils/url-parser.test.ts (/all/settings/file-store/{id}). That breaks the pasted-URL workflow and makes the registry contract misleading. The added tests only cover URL parsing and request wiring; they never assert generated openInHarness output, so this regression is currently untested.

2. Important — In README.md, line 957 and the toolset table starting at lines 1439-1475, the docs were updated to claim 171 resource types / 32 toolsets, but the generated content at this head still contains no File Store or Test Intelligence sections, and the toolset-name table omits both file-store and test-intelligence. A search of the README at the PR head returns no matches for file_store_item, file_store_content, test_failure, File Store, or Test Intelligence. That leaves the public docs less discoverable than the actual registry surface.

Assumptions / open questions:

• I assumed File Store deep links are expected to round-trip to the item-specific UI route because the parser/tests explicitly support .../file-store/{identifier} URLs. If list-page-only deep links are intentional, that contract should be made explicit and the parser/tests should be adjusted to match.
• I did not find a canonical org-scope File Store UI route in-repo. The account-scope mismatch is definite; the exact org-scope route likely needs confirmation from product/UI conventions.

Verified:

• Reviewed the exact current PR head 12458deb4c5f3795d24d12fbe2cb96115c99f7f8 fetched via refs/pull/197/head, against main at 3e3ec347f91bfe72e36ca5f833fd2bc1a2bcd350.
• Inspected the changed registry/toolset, URL parsing, deep-link, README, and test files directly at that SHA.
• Reproduced the current File Store deep-link output from the shipped builder logic.
• I could not execute Vitest in this workspace because dependencies are absent (pnpm test fails with vitest: not found / no node_modules).

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

This template only points to the File Store list page.

Because it never includes the item identifier, every file_store_item result gets the same openInHarness URL instead of linking to the specific file/folder. It also only models the project-scoped route: with the current buildDeepLink() cleanup rules, resource_scope='account' produces /ng/account/{id}/all/setup/resources/file-store, which does not match the account-level File Store URL shape the parser/tests accept (/all/settings/file-store/{id}).

Can we make this template preserve both scope and identifier so openInHarness round-trips back into the url shortcut flow reliably?

[cursor]

The counts were updated here, but the generated README content below still doesn't document the new surfaces.

At this head there are no README matches for file_store_item, file_store_content, test_failure, File Store, or Test Intelligence, and the toolset-name table omits both file-store and test-intelligence. That leaves docs discoverability out of sync with the actual registry contract even though the summary numbers now claim the extra toolsets/resources.

[cursor]

Stale comment

Findings:

1. High: the new multi-request handler abstraction is not wired into Registry.dispatch(), so both test_failure and pipeline.retry_stages are non-functional on the current head. I reproduced this locally: the focused suite fails 10 tests because each path stops after a single raw request instead of invoking the custom orchestration.
2. Medium: file_store_item still over-advertises account/org/project write support. harness_describe surfaces supportedScopes, but the public write tools still omit resource_scope and do not opt into URL-derived scope, so agents cannot discover account/org writes through the documented schema.
3. Medium: File Store openInHarness links still do not round-trip the routes the URL parser accepts. The current template drops the selected file identifier and builds the wrong account-scope route.
4. Medium: the PR is still red on docs sync. On the exact PR head, pnpm typecheck and pnpm build passed, but pnpm docs:check failed with README.md is stale. Run \pnpm docs:generate` to refresh.The visible README catalog also still has nofile-store, test-intelligence, or retry_stages` entries.
5. Low: fileStoreUpdateSchema still reuses the create fields, so harness_describe reports name / type as required on update even though the preflight hydrates them.

Open question / assumption:

• I’m assuming File Store writes are meant to be discoverable through the same public resource_scope contract that harness_describe advertises. If writes are intentionally project-only, the metadata should be narrowed instead.

Verification:

• pnpm test tests/client/harness-client.test.ts tests/registry/file-store.test.ts tests/utils/url-parser.test.ts tests/registry/registry.test.ts tests/tools/tool-handlers.test.ts tests/integration/mock-harness-api.test.ts -> 10 failing tests / 281 total
• pnpm typecheck -> pass
• pnpm build -> pass
• pnpm docs:check -> fail (README.md is stale. Run \pnpm docs:generate` to refresh.`)

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

This adds EndpointSpec.handler, but the current PR never teaches Registry.dispatch() to consult it before building the default single-request path. On the exact PR head, that leaves both new handler-backed features broken at runtime: tests/registry/registry.test.ts and tests/integration/mock-harness-api.test.ts only observe a single raw request for test_failure, and the new retry_stages cases in tests/tools/tool-handlers.test.ts fail for the same reason. Until dispatch branches on spec.handler, this abstraction is only type-level metadata.

[cursor]

supportedScopes is surfaced through harness_describe, but the public write tools still do not expose a top-level resource_scope input and they do not opt into URL-derived scope on create/update/delete. That means file_store_item now advertises account/org/project writes that agents can only reach through undocumented params.resource_scope plumbing. I think this should either be surfaced on harness_create / harness_update / harness_delete or narrowed so the advertised contract stays honest.

[cursor]

This deep link still does not round-trip the File Store URLs the PR now teaches the parser to accept. It omits the selected file_id, so project-scoped reads only land on the collection root, and for account-scoped reads buildDeepLink() collapses this to /ng/account/{id}/all/setup/resources/file-store instead of the tested /ng/account/{id}/all/settings/file-store/{id} route. So openInHarness will still misroute the fetched item.

[cursor]

I re-ran pnpm build && pnpm docs:check on the exact PR head and this branch is still red: README.md is stale. Run \pnpm docs:generate` to refresh.Also, even after generating docs in an isolated worktree, the visible README catalog still has zero mentions offile-store, test-intelligence, test_failure, file_store_item, file_store_content, or retry_stages`, so the public contract is still incomplete even beyond the count drift.

[cursor]

fileStoreUpdateSchema still reuses the create fields verbatim, so harness_describe reports name and type as required even though hydrateFileStoreUpdate() backfills them and the new tests intentionally update with only content / mime_type. That makes the published update contract stricter than the runtime behavior.

[cursor]

Findings:

1. Critical: EndpointSpec.handler is added but never executed by Registry.executeSpec(). On the live PR head, both new multi-request features (test_failure.list and pipeline.retry_stages) fall back to the generic single-request path and fail their own tests. I reproduced this with pnpm test tests/registry/registry.test.ts tests/integration/mock-harness-api.test.ts tests/tools/tool-handlers.test.ts; the new cases expect 3-5 client calls and only observe 1.
2. Important: README.md is still stale on the live head. pnpm build && pnpm docs:check fails, the README still claims 171 resource types / 32 toolsets and 32 of 33 defaults, while the built registry loads 172 / 33 by default (190 / 34 with HARNESS_TOOLSETS=+ai-evals). The catalog also still has no file-store or test-intelligence entries.
3. Important: File Store still over-advertises multi-scope writes. supportedScopes tells agents that file_store_item supports account/org/project scope, but the public write tools still do not expose resource_scope and still do not opt into URL-derived scope. That makes the harness_describe contract looser than the actual harness_create / harness_update / harness_delete surface.
4. Medium: File Store openInHarness links still do not round-trip the new parser paths. The template omits file_id and only models the project collection route, so account-scoped reads and item-specific links both collapse to a generic list page.

Assumption:

• I’m treating harness_describe and README.md as agent/public contracts, consistent with the repo’s architecture rules.

Verification:

• pnpm install --frozen-lockfile
• pnpm typecheck
• pnpm build
• pnpm docs:check
• pnpm test tests/registry/registry.test.ts tests/integration/mock-harness-api.test.ts tests/tools/tool-handlers.test.ts
• pnpm test tests/registry/file-store.test.ts tests/utils/url-parser.test.ts

  

_{Sent by Cursor Automation: Sunil On Demand Architecture Review}

[cursor]

EndpointSpec.handler is only useful if the dispatcher actually consumes it. On the current PR head, Registry.executeSpec() never checks spec.handler, so both new call sites (test_failure.list and pipeline.retry_stages) still fall through to the generic single-request path. I reproduced that with pnpm test tests/registry/registry.test.ts tests/integration/mock-harness-api.test.ts tests/tools/tool-handlers.test.ts: the new flows expect 3-5 client calls and only see 1.

[cursor]

This README refresh is still stale on the live PR head. After pnpm build, pnpm docs:check fails here, the registry loads 172 resource types / 33 toolsets by default (190 / 34 with HARNESS_TOOLSETS=+ai-evals), but the README still says 171 / 32 and 32 of 33. It also still has no file-store, test-intelligence, or test_failure entries, so the public docs contract is behind the actual registry surface.

[cursor]

supportedScopes is resource-wide metadata surfaced through harness_describe, so this now advertises account/org/project support for create/update/delete as well. The problem is that the public write tools still do not publish a top-level resource_scope input and still call applyUrlDefaults() without includeResourceScope, so agents cannot actually express those account/org File Store writes through the documented tool schemas. Either plumb resource_scope through harness_create / harness_update / harness_delete or narrow the advertised scope contract.

[cursor]

This template still cannot round-trip the new File Store URL-parser paths. It omits {file_id}, so every item links to the same collection page, and it only models the project route even though tests/utils/url-parser.test.ts now accepts account URLs like /all/settings/file-store/{id}. That leaves openInHarness one-way for account-scoped reads and non-specific even for project-scoped items.