NVIDIA / NVIDIA/NemoClaw

[DeepSeek Harness 2/8] Produce a reproducible DeepSeek Harness candidate runtime

Open
#9,330 0 comments 0 reactions 0 assignees View on GitHub
area: ci area: onboarding area: packaging integration: deepseek-harness
Dominant language
TypeScript
Stars
22.5k
Forks
3.1k
Avg merge
1d 1h
Merged PRs (30d)
715

Description

## Summary

Produce the exact, integrity-verifiable DeepSeek Harness runtime artifacts and managed images required for candidate-only NemoClaw qualification.

Parent epic: #9328

Depends on #9329, **[DeepSeek Harness 1/8] Accept product scope, ownership, threat model, and compatibility matrix**.

Gate 3 consumes the entry points and image from this issue. Gates 4 through 7 consume the exact candidate identities and artifacts. Gate 8 alone owns public activation.

## Problem Statement

NemoClaw has no owned DeepSeek Harness agent manifest, locked runtime closure, managed image, startup wrapper, final configuration-overlay location, or candidate publication contract.

Installing `@deepseek-ai/dsh` dynamically does not establish a reproducible runtime. The package is prerelease software with a large workspace-published dependency family, browser artifacts, profile auto-initialization, package symlink repair, and possible native or lifecycle-script dependencies.

An image that installs packages on first boot, uses a floating npm version, omits built Web assets, or accepts writable user patches as managed authority cannot be qualified or safely activated.

## Desired Behavior

The repository contains one DeepSeek Harness agent directory that builds a complete, non-root, dual-architecture candidate runtime from an exact lockfile and reviewed dependency closure.

The candidate image contains every accepted runtime and browser artifact before publication. Startup does not contact a package registry, execute an installer, update DSH, or install a profile plugin.

Protected candidate paths can select each exact image digest. Public agent selection and the shipped all-agent cohort remain unchanged until Gate 8.

## Accepted contract dependency

Implementation must copy the exact accepted Gate 1 values into source-owned contracts rather than silently retaining investigation defaults. This includes:

- package version, integrity, source commit, and Node.js runtime;
- accepted architectures and compute runtime;
- Web/headless surface matrix and entry points;
- accepted preset and tool roster;
- managed final-overlay mechanism;
- state path classification needed by the manifest;
- browser bind and port contract when Web is accepted.

If any value is still undecided, this issue is blocked rather than authorized to choose it.

## Implementation Idea

Use the manifest-first layout:

```text
agents/deepseek-harness/
manifest.yaml
start.sh
generate-config.ts
managed.cordis.patch.yml
policy-additions.yaml
dependency-review.md
package.json
package-lock.json
Dockerfile
Dockerfile.base
```

Exact filenames may follow current repository conventions, but the ownership boundaries must remain visible.

The managed Cordis overlay must live outside writable `$DSH_HOME` state, be owned by the image/runtime envelope, and be passed after shipped, profile, and home layers. Gate 5 supplies the accepted inference configuration and Gate 6 supplies the full policy roster; this issue establishes the immutable precedence mechanism and candidate artifact.

The accepted built-in profiles may auto-initialize deterministically from image-shipped templates. Auto-initialization must not fetch packages or make generated profile/package symlinks portable state.

## Scope

- `agents/deepseek-harness/manifest.yaml` with canonical identity, exact version probe, runtime surfaces, health metadata where accepted, architectures, startup-profile contract, state declarations, and package metadata.
- Exact `package.json` and lockfile for the complete published runtime closure.
- Dependency, license, install-script, native-addon, executable, and browser-artifact review.
- An accepted Node.js base pinned by immutable identity.
- Non-root AMD64 and ARM64 image builds.
- Image-bundled Web frontend and shipped profile/preset resources when Web is accepted.
- Root-owned startup wrapper and final managed overlay.
- Deterministic profile initialization without registry access.
- Version, configuration-dump, binary, frontend, and permission smoke probes.
- Candidate managed-image catalog, repository-map, and protected qualification registration.
- Exact per-architecture image digests and provenance.
- Candidate authority that remains empty until Gate 7 evidence is accepted and Gate 8 activates the runtime.

## Constraints and Non-goals

- Do not use a floating package selector, image tag, base-image tag without immutable resolution, or runtime auto-update.
- Do not run `npm`, `pnpm`, `npx`, profile plugin installation, or another package installer at first boot.
- Do not assume `--ignore-scripts` works. Review every required lifecycle script or native addon and allow only the accepted minimum.
- Do not build the stock image from a Dockerfile during user onboarding.
- Do not download Web assets at runtime.
- Do not put an upstream provider credential, direct-provider API key, route secret, or test credential in the image or build provenance.
- Do not place managed route or policy authority in writable `$DSH_HOME`, `settings.yaml`, a user profile patch, or the invoking workspace.
- Do not restore generated `node_modules`, package symlinks, caches, or auto-initialized shipped profiles as user state.
- Do not add DeepSeek Harness-specific Docker, Podman, lifecycle, snapshot, or recovery code.
- Do not add DeepSeek Harness to public choices or the active shipped-image cohort; Gate 8 owns activation.
- Do not claim Web authentication, inference compatibility, complete policy enforcement, state recovery, or live release qualification in this artifact slice.

## Observable acceptance tests

Repository tests must prove:

1. The manifest parses and its canonical ID, version, architecture, runtime, configuration, and state fields equal the accepted Gate 1 contract.
2. The lockfile resolves one exact version and integrity for every production dependency; an altered integrity, missing package, unexpected package, or unlocked dependency fails.
3. The dependency review enumerates all install scripts, native addons, executable bins, licenses, and shipped browser/profile assets and fails on unreviewed additions.
4. The image build performs no network-dependent package operation after its locked install layer and first boot performs no package operation at all.
5. `/usr/local/bin/dsh --version` reports the exact accepted version on AMD64 and ARM64.
6. Web help and the accepted Web configuration dump work from built artifacts without a source checkout when Web is accepted.
7. The accepted headless configuration dump works without a source checkout when headless is accepted.
8. The image contains the accepted Web frontend, profile templates, preset resources, final managed overlay, and startup wrapper.
9. The runtime user is non-root; `$DSH_HOME` is owner-only; managed artifacts and the final overlay are not writable by that user.
10. A writable home or profile patch cannot outrank or replace a sentinel managed row supplied by the final overlay.
11. First boot with package-registry egress denied still initializes only the accepted deterministic profiles and passes its smoke probes.
12. Image and filesystem scans find no upstream provider credential, direct-provider test key, route secret, `.credentials.yaml`, or populated `.env`.
13. Candidate publication produces exact AMD64 and ARM64 digests and rejects a partial architecture cohort.
14. Protected candidate selection can resolve those exact digests without a host Dockerfile build while public selection still rejects `deepseek-harness`.
15. Shared compute-runtime and managed-image tests can substitute a non-Docker provider identity without changing DeepSeek Harness artifacts.

## Required evidence

Attach or link a bounded candidate evidence manifest containing:

- NemoClaw candidate commit;
- accepted Gate 1 decision revision;
- package version, npm integrity, source commit, lockfile digest, dependency-review digest, and license/SBOM artifact;
- Node.js and base-image identities;
- AMD64 and ARM64 image digests plus build provenance;
- version, frontend, profile, configuration-precedence, permission, and offline-first-boot probe results;
- candidate catalog and publication-contract results;
- a credential scan attestation;
- confirmation that the accepted qualification-receipt list and public shipped cohort remain unchanged.

The repository-owned `dependency-review.md` must explain every approved install script/native addon and the condition that triggers re-review. Package or transitive-closure drift invalidates this evidence.

## Documentation impact

- Document the image-build source as a CI/publication input, not a user onboarding path.
- Record the exact candidate package and image identities in the repository-owned artifact contract.
- Add maintainer instructions for updating the package, regenerating the lockfile, reviewing closure drift, and producing new candidate digests.
- Do not add public user onboarding documentation before Gate 8.

## Acceptance Criteria

- [ ] Gate 1 is accepted and every artifact matches its exact contract.
- [ ] `agents/deepseek-harness/manifest.yaml` defines the candidate runtime without making it public.
- [ ] Package, lockfile, source, dependency review, base image, and per-architecture image identities are immutable and integrity-verifiable.
- [ ] Required install scripts, native addons, executables, licenses, and Web/profile artifacts are explicitly reviewed.
- [ ] AMD64 and ARM64 candidate images build and pass the same non-root artifact probes.
- [ ] The complete accepted runtime works from the image without a source checkout or first-boot package installation.
- [ ] The root-owned final overlay wins over writable home and profile layers in a deterministic negative test.
- [ ] No provider credential or test secret appears in the package inputs, image, environment defaults, provenance, or evidence.
- [ ] Protected qualification resolves exact image digests without a host build.
- [ ] Partial publication, lockfile drift, integrity drift, and missing browser/profile artifacts fail closed.
- [ ] DeepSeek Harness remains absent from public selection and the active shipped-image cohort.
- [ ] No artifact contains a DeepSeek Harness-specific compute-runtime lifecycle branch.
- [ ] The candidate evidence manifest and maintainer artifact documentation are complete.

## Category

Feature

## Checklist

- [x] I searched existing issues and this is not a duplicate.
- [x] I described the problem and desired behavior.

Contributor guide

Open the contributing guide

Research direction

Start by reading dependency issue #9329 and the accepted Gate 1 contract, then compare current agent conventions with the listed agents/deepseek-harness files. Review manifest.yaml, package.json, package-lock.json, Dockerfile, Dockerfile.base, start.sh, generate-config.ts, and dependency-review.md before running the repository’s manifest, image, and offline-start probes. Done means immutable AMD64 and ARM64 candidate artifacts pass the stated acceptance tests without public activation.

Written by the indexing model from the issue text.

Assessment

Tech stack
docker, node.js, typescript
Domain
build-system, ci-cd, devops, infrastructure
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.