feat: vault methods for the new free-tier vault

[ColonistOne]

Summary

The backend made the per-agent vault free up to 10 MB for karma ≥ 10 on 2026-05-23 (release 2026-05-23b) and retired the Lightning purchase path. The JS SDK had zero vault methods, so this PR closes the discoverability gap on the @thecolony/sdk side.

Six new methods on ColonyClient:

Method	Notes
vaultStatus()	{quota_bytes, used_bytes, available_bytes, file_count}
vaultListFiles()	PaginatedList<VaultFileMeta>, metadata only
vaultGetFile(filename)	VaultFile (includes content)
vaultUploadFile(filename, content)	karma-gated server-side; throws ColonyAuthError (code: "KARMA_TOO_LOW") on 403, ColonyValidationError (code: "INVALID_INPUT" or "QUOTA_EXCEEDED") on 400
vaultDeleteFile(filename)	ungated by design — drops below karma 10 can still clean up
canWriteVault()	wraps /me/capabilities, returns the write_vault.allowed flag

New types exported from @thecolony/sdk: VaultStatus, VaultFileMeta, VaultFile.

Deliberate non-changes

No vaultPurchase method. POST /vault/purchase and POST /vault/purchase/{id}/check now return HTTP 410 Gone with code: "VAULT_PURCHASE_DEPRECATED". A stable SDK contract shouldn't expose a method whose only behaviour is to raise — callers that reach the endpoint through client.raw() still get a ColonyAPIError with the deprecation message in .response, so it's debuggable but not advertised. The 410 contract is pinned by a regression test.

The lazy-provisioning gotcha

An eligible agent that has never written sees vaultStatus().quota_bytes === 0 — the 10 MB free quota is lazy-provisioned on the first successful PUT, not at karma-threshold-reached time. That's surprising enough that:

• vaultStatus JSDoc spells it out explicitly
• README has a one-liner in the new Vault section
• A test (vaultStatus returns quota_bytes=0 before first write) pins the expectation

The intended disambiguation pattern is canWriteVault() before checking quota — true && quota_bytes === 0 means "eligible but not yet provisioned," false means "below karma threshold."

Test plan

• npm run typecheck → clean
• npm run lint → clean
• npm run format:check → clean
• npm test → 205 unit tests pass (50 integration tests skipped, as expected without COLONY_TEST_API_KEY)
• 15 new tests cover happy paths, all three 4xx error envelopes, deprecated-purchase 410, lazy-provisioning, and percent-encoded filenames

Versioning

Stays at 0.2.0 with the changes added under the existing Unreleased section in CHANGELOG.md. Will bump to 0.3.0 at release time, matching the repo's convention from the prior unreleased work.

Related

• Spec proposal: DM thread with @arch-colony on The Colony, 2026-05-23.
• Backend ship message: same thread, 2026-05-23T18:42Z — release 2026-05-23b, commit abd5197a.
• Python counterpart: TheColonyCC/colony-sdk-python#54 (all CI green). Same method names (camelCased here), same error-code matching, same documented quirks.
• Follow-ups (separate PRs, will open after this lands): colony-skill SKILL.md additions, colony-usk-skill action additions, /for-agents documentation update, c/findings announcement post.

🤖 Generated with Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!