fix(api): expose legacy zip artifact aliases

[vincentkoc]

Summary

• expose legacy ZIP artifact aliases for older OpenClaw clients without changing npm-pack metadata
• use only the stored archive SHA (sha256hash) for legacy ZIP archive integrity aliases; never use publish-time integritySha256 as downloaded ZIP integrity
• update both schema package surfaces and add artifact endpoint regressions for hash precedence and missing archive-hash omission

Tests

• bunx vitest run convex/httpApiV1.handlers.test.ts --testNamePattern "package artifact endpoint"
• bun run --cwd packages/schema build
• bunx tsc -p packages/schema/tsconfig.json --noEmit
• bunx tsc -p packages/clawhub/tsconfig.json --noEmit
• bun run format:check convex/httpApiV1.handlers.test.ts convex/httpApiV1/packagesV1.ts packages/schema/src/packages.ts packages/schema/dist/packages.d.ts packages/schema/dist/packages.js packages/clawhub/src/schema/packages.ts
• bun run --cwd packages/clawhub verify:build
• bun run --cwd packages/clawhub build
• bun run lint

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clawhub	Ready	Preview, Comment	May 3, 2026 5:32pm

[clawsweeper]

Codex review: needs maintainer review before merge.

Summary
The PR adds optional legacy ZIP artifact alias fields to API artifact metadata, updates package schema outputs, and adds package artifact endpoint regression coverage.

Reproducibility: yes. Source inspection of current main shows legacy ZIP artifact responses are built without artifactKind, artifactSha256, packageName, version, or source, so the PR's regression test would fail on main by inspection.

Next step before merge
This is a draft maintainer PR with no narrow automated repair needed; the remaining action is maintainer readiness, CI, and normal review.

Security
Cleared: The diff only changes API response metadata, schema output, and tests; it does not alter dependencies, workflows, secrets, install scripts, or artifact execution paths.

Review details

Best possible solution:

Land the narrow compatibility change after the maintainer takes the PR out of draft and checks pass, keeping npm-pack responses on the newer metadata shape.

Do we have a high-confidence way to reproduce the issue?

Yes. Source inspection of current main shows legacy ZIP artifact responses are built without artifactKind, artifactSha256, packageName, version, or source, so the PR's regression test would fail on main by inspection.

Is this the best way to solve the issue?

Yes. Updating the shared artifact response helper plus the public schema is a narrow maintainable fix for the compatibility aliases while preserving the newer npm-pack shape.

What I checked:

• Current main legacy artifact shape: Current main's toReleaseArtifact returns only kind, sha256, and format for legacy ZIP artifacts, so the compatibility aliases are not already implemented on main. (convex/httpApiV1/packagesV1.ts:367, 59fc54ff641b)
• Affected endpoint call sites: The package artifact and package version endpoints both build artifact metadata through toReleaseArtifact, matching the PR's narrow response-surface change. (convex/httpApiV1/packagesV1.ts:2349, 59fc54ff641b)
• Current schema lacks aliases: Current main's package artifact schema accepts the newer artifact fields but not the proposed legacy alias fields. (packages/schema/src/packages.ts:96, 59fc54ff641b)
• API documentation surface: The docs describe /api/v1/packages/{name}/versions/{version}/artifact as explicit resolver metadata for legacy ZIP and ClawPack package versions. (docs/http-api.md:381, 59fc54ff641b)
• Feature history: Recent current-main history for the package API, ClawPack metadata, and artifact URL code is concentrated in Vincent Koc commits.

Likely related people:

• vincentkoc: Recent current-main commits cover the package API, ClawPack metadata storage, scoped package routing, and artifact URL behavior touched by this PR. (role: recent maintainer and adjacent owner; confidence: high; commits: 56743ce3d87e, 8234c92dcf61, 343781a66811; files: convex/httpApiV1/packagesV1.ts, convex/httpApiV1.handlers.test.ts, convex/packages.ts)

Remaining risk / open question:

• The PR is still draft, so final merge readiness should wait for the maintainer to mark it ready and for required checks to pass.
• The new regression coverage focuses on the artifact endpoint; version-response alias expectations are covered by the shared helper but not by a dedicated test in the provided diff.

Codex review notes: model gpt-5.5, reasoning high; reviewed against 59fc54ff641b.